Provided lots of missing Javadoc.

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@1056530 13f79535-47bb-0310-9956-ffa450edef68

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

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
+ * Structure used to store an {@link HttpResponse} in a cache. Some entries
- * on system resources that may require explicit deallocation. In such a case {@link #getResource()}
+ * can optionally depend on system resources that may require explicit
- * should return a non-null instance of {@link Resource} that must be deallocated by calling
+ * 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<String, String> getVariantMap() {
         if (variantMap == null) {
             throw new UnsupportedOperationException("variant maps not" +

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;

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;

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;
 

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
      *            <code>null</code> if nonexistent
-     * @return CacheEntry the cache entry that should replace it, again,
+     * @return HttpCacheEntry the cache entry that should replace it, again,
-     *         possible <code>null</code>
+     *         possibly <code>null</code>
      *
      * @since 4.1
      */

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
  */

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;
     }

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();
 
 }

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;
 
 }