The {@link CachingHttpClient} is meant to be a drop-in replacement for + *
+ * The {@link CachingHttpClient} is meant to be a drop-in replacement for * a {@link DefaultHttpClient} that transparently adds client-side caching. * The current implementation is conditionally compliant with HTTP/1.1 * (meaning all the MUST and MUST NOTs are obeyed), although quite a lot, @@ -93,9 +94,11 @@ * passing in a {@link CacheConfig}. Note that all of the usual client * related configuration you want to do vis-a-vis timeouts and connection * pools should be done on this backend client before constructing a {@code - * CachingHttpClient} from it.
+ * CachingHttpClient} from it. + * * - *Generally speaking, the {@code CachingHttpClient} is implemented as a + *
+ * Generally speaking, the {@code CachingHttpClient} is implemented as a * Decorator * of the backend client; for any incoming request it attempts to satisfy * it from the cache, but if it can't, or if it needs to revalidate a stale @@ -106,15 +109,17 @@ * or the cache may make a conditional request on your behalf to the origin). * This notion of "semantic transparency" means you should be able to drop * a {@link CachingHttpClient} into an existing application without breaking - * anything.
+ * anything. + * * - *Folks that would like to experiment with alternative storage backends + *
+ * Folks that would like to experiment with alternative storage backends * should look at the {@link HttpCacheStorage} interface and the related * package documentation there. You may also be interested in the provided * {@link org.apache.http.impl.client.cache.ehcache.EhcacheHttpCacheStorage * EhCache} and {@link * org.apache.http.impl.client.cache.memcached.MemcachedHttpCacheStorage - * memcached} storage backends.
+ * memcached} storage backends. * * @since 4.1 * diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java index 2a3f02515..3c4a55e7a 100644 --- a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java +++ b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CacheConfig.java @@ -98,7 +98,7 @@ * CacheConfig#getAsynchronousWorkerIdleLifetimeSecs() maximum time they * can be idle before being reclaimed}. You can also control the {@link * CacheConfig#getRevalidationQueueSize() size of the queue} used for - * revalidations when there aren't enough workers to keep up with demand. + * revalidations when there aren't enough workers to keep up with demand. */ public class CacheConfig implements Cloneable { diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingExec.java b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingExec.java index 937d0fdc6..822c3408c 100644 --- a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingExec.java +++ b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingExec.java @@ -72,12 +72,17 @@ import org.apache.http.util.VersionInfo; /** + ** Request executor in the request execution chain that is responsible for - * transparent client-side caching. The current implementation is conditionally + * transparent client-side caching. + *
+ *+ * The current implementation is conditionally * compliant with HTTP/1.1 (meaning all the MUST and MUST NOTs are obeyed), * although quite a lot, though not all, of the SHOULDs and SHOULD NOTs * are obeyed too. - *
+ * + ** Folks that would like to experiment with alternative storage backends * should look at the {@link HttpCacheStorage} interface and the related * package documentation there. You may also be interested in the provided @@ -85,10 +90,12 @@ * EhCache} and {@link * org.apache.http.impl.client.cache.memcached.MemcachedHttpCacheStorage * memcached} storage backends. - *
+ * + ** Further responsibilities such as communication with the opposite * endpoint is delegated to the next executor in the request execution * chain. + *
* * @since 4.3 */ diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ManagedHttpCacheStorage.java b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ManagedHttpCacheStorage.java index 0f74a8c3b..0a02658de 100644 --- a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ManagedHttpCacheStorage.java +++ b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/ManagedHttpCacheStorage.java @@ -41,25 +41,32 @@ import org.apache.http.util.Args; /** + ** {@link HttpCacheStorage} implementation capable of deallocating resources associated with - * the cache entries. This cache keeps track of cache entries using + * the cache entries. + *
+ * This cache keeps track of cache entries using * {@link java.lang.ref.PhantomReference} and maintains a collection of all resources that * are no longer in use. The cache, however, does not automatically deallocates associated * resources by invoking {@link Resource#dispose()} method. The consumer MUST periodically * call {@link #cleanResources()} method to trigger resource deallocation. The cache can be * permanently shut down using {@link #shutdown()} method. All resources associated with * the entries used by the cache will be deallocated. - *
+ * + ** This {@link HttpCacheStorage} implementation is intended for use with {@link FileResource} * and similar. - *
+ * + ** Compatibility note. Prior to version 4.4 this storage implementation used to dispose of * all resource entries upon {@link #close()}. As of version 4.4 the {@link #close()} method * disposes only of those resources that have been explicitly removed from the cache with * {@link #removeEntry(String)} method. - *
+ * + ** The {@link #shutdown()} ()} method can still be used to shut down the storage and dispose of * all resources currently managed by it. + *
* * @since 4.1 */ diff --git a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedCacheEntry.java b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedCacheEntry.java index 7e5da8508..80b346bea 100644 --- a/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedCacheEntry.java +++ b/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/memcached/MemcachedCacheEntry.java @@ -65,8 +65,9 @@ public interface MemcachedCacheEntry { * {@link #getStorageKey()} and {@link #getHttpCacheEntry()}. This * should be viewed as an atomic operation on the * {@code MemcachedCacheEntry}. + * * @param bytes serialized representation - * @throws {@link MemcachedSerializationException} if deserialization + * @throws MemcachedSerializationException if deserialization * fails. In this case, the prior values for {{@link #getStorageKey()} * and {@link #getHttpCacheEntry()} should remain unchanged. */ 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 5a302f940..39f703d1c 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,41 +45,49 @@ import org.apache.http.impl.client.cache.CacheConfig; /** - *This class is a storage backend that uses an external memcached + *
+ * 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: + *
** Note that in a shared memcached pool setting you may wish to make use * of the Ketama consistent hashing algorithm to reduce the number of * cache misses that might result if one of the memcached cluster members * fails (see the * KetamaConnectionFactory). *
- * - *Because memcached places limits on the size of its keys, we need to + *
+ * Because memcached places limits on the size of its keys, we need to * introduce a key hashing scheme to map the annotated URLs the higher-level * caching HTTP client wants to use as keys onto ones that are suitable * for use with memcached. Please see {@link KeyHashingScheme} if you would - * like to use something other than the provided {@link SHA256KeyHashingScheme}.
+ * like to use something other than the provided {@link SHA256KeyHashingScheme}. + * * - *Because this hashing scheme can potentially result in key collisions (though + *
+ * Because this hashing scheme can potentially result in key collisions (though * highly unlikely), we need to store the higher-level logical storage key along * with the {@link HttpCacheEntry} so that we can re-check it on retrieval. There * is a default serialization scheme provided for this, although you can provide * your own implementations of {@link MemcachedCacheEntry} and - * {@link MemcachedCacheEntryFactory} to customize this serialization.
+ * {@link MemcachedCacheEntryFactory} to customize this serialization. + * * - *Please refer to the
+ *
+ * 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.