diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java index b49362878..e7fb0a2f2 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java @@ -29,6 +29,7 @@ package org.apache.http.client.cache; import org.apache.http.annotation.Immutable; /** + * Records static constants for various HTTP header names. * @since 4.1 */ @Immutable diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java index 9dcaca83a..5806961ff 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java @@ -42,9 +42,10 @@ import org.apache.http.annotation.Immutable; import org.apache.http.message.HeaderGroup; /** - * Structure used to store an {@link HttpResponse} in a cache. Some entries can optionally depend - * on system resources that may require explicit deallocation. In such a case {@link #getResource()} - * should return a non-null instance of {@link Resource} that must be deallocated by calling + * Structure used to store an {@link HttpResponse} in a cache. Some entries + * can optionally depend on system resources that may require explicit + * deallocation. In such a case {@link #getResource()} should return a non + * null instance of {@link Resource} that must be deallocated by calling * {@link Resource#dispose()} method when no longer used. * * @since 4.1 @@ -164,7 +165,9 @@ public class HttpCacheEntry implements Serializable { * Header[] from original HTTP Response * @param resource representing origin response body * @param variantMap describing cache entries that are variants - * of this parent entry; each cache key should map to itself + * of this parent entry; this maps a "variant key" (derived + * from the varying request headers) to a "cache key" (where + * in the cache storage the particular variant is located) */ public HttpCacheEntry(Date requestDate, Date responseDate, StatusLine statusLine, Header[] responseHeaders, @@ -173,46 +176,88 @@ public class HttpCacheEntry implements Serializable { resource, null, variantMap); } + /** + * Returns the {@link StatusLine} from the origin {@link HttpResponse}. + */ public StatusLine getStatusLine() { return this.statusLine; } + /** + * Returns the {@link ProtocolVersion} from the origin {@link HttpResponse}. + */ public ProtocolVersion getProtocolVersion() { return this.statusLine.getProtocolVersion(); } + /** + * Gets the reason phrase from the origin {@link HttpResponse}, for example, + * "Not Modified". + */ public String getReasonPhrase() { return this.statusLine.getReasonPhrase(); } + /** + * Returns the HTTP response code from the origin {@link HttpResponse}. + */ public int getStatusCode() { return this.statusLine.getStatusCode(); } + /** + * Returns the time the associated origin request was initiated by the + * caching module. + * @return {@link Date} + */ public Date getRequestDate() { return requestDate; } + /** + * Returns the time the origin response was received by the caching module. + * @return {@link Date} + */ public Date getResponseDate() { return responseDate; } + /** + * Returns all the headers that were on the origin response. + */ public Header[] getAllHeaders() { return responseHeaders.getAllHeaders(); } + /** + * Returns the first header from the origin response with the given + * name. + */ public Header getFirstHeader(String name) { return responseHeaders.getFirstHeader(name); } + /** + * Gets all the headers with the given name that were on the origin + * response. + */ public Header[] getHeaders(String name) { return responseHeaders.getHeaders(name); } + /** + * Returns the {@link Resource} containing the origin response body. + */ public Resource getResource() { return this.resource; } + /** + * Indicates whether the origin response indicated the associated + * resource had variants (i.e. that the Vary header was set on the + * origin response). + * @return {@code true} if this cached response was a variant + */ public boolean hasVariants() { return getFirstHeader(HeaderConstants.VARY) != null; } @@ -225,6 +270,15 @@ public class HttpCacheEntry implements Serializable { return Collections.unmodifiableSet(variantURIs); } + /** + * Returns an index about where in the cache different variants for + * a given resource are stored. This maps "variant keys" to "cache keys", + * where the variant key is derived from the varying request headers, + * and the cache key is the location in the + * {@link org.apache.http.client.cache.HttpCacheStorage} where that + * particular variant is stored. The first variant returned is used as + * the "parent" entry to hold this index of the other variants. + */ public Map getVariantMap() { if (variantMap == null) { throw new UnsupportedOperationException("variant maps not" + diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java index 9ec21a7ba..bec3555b9 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java @@ -28,6 +28,10 @@ package org.apache.http.client.cache; import java.io.IOException; +/** + * Thrown if serialization or deserialization of an {@link HttpCacheEntry} + * fails. + */ public class HttpCacheEntrySerializationException extends IOException { private static final long serialVersionUID = 9219188365878433519L; diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java index 9658527b3..a834d068a 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java @@ -30,6 +30,11 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; +/** + * Used by some {@link HttpCacheStorage} implementations to serialize + * {@link HttpCacheEntry} instances to a byte representation before + * storage. + */ public interface HttpCacheEntrySerializer { public void writeTo(HttpCacheEntry entry, OutputStream os) throws IOException; diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java index 571077c9c..c5ef92838 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java @@ -29,16 +29,49 @@ package org.apache.http.client.cache; import java.io.IOException; /** + * New storage backends should implement this {@link HttpCacheStorage} + * interface. They can then be plugged into the existing + * {@link org.apache.http.impl.client.cache.CachingHttpClient} + * implementation. + * * @since 4.1 */ public interface HttpCacheStorage { + /** + * Store a given cache entry under the given key. + * @param key where in the cache to store the entry + * @param entry cached response to store + * @throws IOException + */ void putEntry(String key, HttpCacheEntry entry) throws IOException; + /** + * Retrieves the cache entry stored under the given key + * or null if no entry exists under that key. + * @param key cache key + * @return an {@link HttpCacheEntry} or {@code null} if no + * entry exists + * @throws IOException + */ HttpCacheEntry getEntry(String key) throws IOException; + /** + * Deletes/invalidates/removes any cache entries currently + * stored under the given key. + * @param key + * @throws IOException + */ void removeEntry(String key) throws IOException; + /** + * Atomically applies the given callback to update an + * existing cache entry under a given key. + * @param key indicates which entry to modify + * @param callback performs the update + * @throws IOException + * @throws HttpCacheUpdateException + */ void updateEntry( String key, HttpCacheUpdateCallback callback) throws IOException, HttpCacheUpdateException; diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java index 431886190..bd017a329 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java @@ -28,16 +28,22 @@ package org.apache.http.client.cache; import java.io.IOException; +/** + * Used for atomically updating entries in a {@link HttpCacheStorage} + * implementation. The current entry (if any) is fed into an implementation + * of this interface, and the new, possibly updated entry (if any) + * should be returned. + */ public interface HttpCacheUpdateCallback { /** * Returns the new cache entry that should replace an existing one. * * @param existing - * the cache entry current in-place in the cache, possibly + * the cache entry currently in-place in the cache, possibly * null if nonexistent - * @return CacheEntry the cache entry that should replace it, again, - * possible null + * @return HttpCacheEntry the cache entry that should replace it, again, + * possibly null * * @since 4.1 */ diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java index c58ae32c9..956cc8b40 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java @@ -27,7 +27,8 @@ package org.apache.http.client.cache; /** - * Signals that {@link HttpCacheStorage} encountered an error performing an update operation. + * Signals that {@link HttpCacheStorage} encountered an error performing an + * update operation. * * @since 4.1 */ diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java index d0717a12c..fd2cf988f 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java @@ -29,6 +29,9 @@ package org.apache.http.client.cache; import org.apache.http.annotation.NotThreadSafe; /** + * Used to limiting the size of an incoming response body of + * unknown size that is optimistically being read in anticipation + * of caching it. * @since 4.1 */ @NotThreadSafe // reached @@ -37,20 +40,35 @@ public class InputLimit { private final long value; private boolean reached; + /** + * Create a limit for how many bytes of a response body to + * read. + * @param value maximum length in bytes + */ public InputLimit(long value) { super(); this.value = value; this.reached = false; } + /** + * Returns the current maximum limit that was set on + * creation. + */ public long getValue() { return this.value; } + /** + * Used to report that the limit has been reached. + */ public void reached() { this.reached = true; } + /** + * Returns {@code true} if the input limit has been reached. + */ public boolean isReached() { return this.reached; } diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java index 74f5e9c4a..8a3ccad1e 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java @@ -31,16 +31,30 @@ import java.io.InputStream; import java.io.Serializable; /** - * Represents a disposable system resource. + * Represents a disposable system resource used for handling + * cached response bodies. * * @since 4.1 */ public interface Resource extends Serializable { + /** + * Returns an {@link InputStream} from which the response + * body can be returned. + * @throws IOException + */ InputStream getInputStream() throws IOException; + /** + * Returns the length in bytes of the response body. + */ long length(); + /** + * Indicates the system no longer needs to keep this + * response body and any system resources associated with + * it may be reclaimed. + */ void dispose(); } diff --git a/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java b/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java index 063b842e1..5d857426d 100644 --- a/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java +++ b/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java @@ -30,14 +30,38 @@ import java.io.IOException; import java.io.InputStream; /** - * Generates {@link Resource} instances. + * Generates {@link Resource} instances for handling cached + * HTTP response bodies. * * @since 4.1 */ public interface ResourceFactory { + /** + * Creates a {@link Resource} from a given response body. + * @param requestId a unique identifier for this particular + * response body + * @param instream the original {@link InputStream} + * containing the response body of the origin HTTP response. + * @param limit maximum number of bytes to consume of the + * response body; if this limit is reached before the + * response body is fully consumed, mark the limit has + * having been reached and return a {@code Resource} + * containing the data read to that point. + * @return a {@code Resource} containing however much of + * the response body was successfully read. + * @throws IOException + */ Resource generate(String requestId, InputStream instream, InputLimit limit) throws IOException; + /** + * Clones an existing {@link Resource}. + * @param requestId unique identifier provided to associate + * with the cloned response body. + * @param resource the original response body to clone. + * @return {@code Resource} + * @throws IOException + */ Resource copy(String requestId, Resource resource) throws IOException; }