Return-Path: Delivered-To: apmail-hc-commits-archive@www.apache.org Received: (qmail 29445 invoked from network); 7 Jan 2011 22:02:20 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 7 Jan 2011 22:02:20 -0000 Received: (qmail 50192 invoked by uid 500); 7 Jan 2011 22:02:20 -0000 Delivered-To: apmail-hc-commits-archive@hc.apache.org Received: (qmail 50163 invoked by uid 500); 7 Jan 2011 22:02:19 -0000 Mailing-List: contact commits-help@hc.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "HttpComponents Project" Delivered-To: mailing list commits@hc.apache.org Received: (qmail 50156 invoked by uid 99); 7 Jan 2011 22:02:19 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 07 Jan 2011 22:02:19 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 07 Jan 2011 22:02:16 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id E59A523888D2; Fri, 7 Jan 2011 22:01:54 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1056530 - /httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/ Date: Fri, 07 Jan 2011 22:01:54 -0000 To: commits@hc.apache.org From: jonm@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20110107220154.E59A523888D2@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: jonm Date: Fri Jan 7 22:01:54 2011 New Revision: 1056530 URL: http://svn.apache.org/viewvc?rev=1056530&view=rev Log: Provided lots of missing Javadoc. Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HeaderConstants.java Fri Jan 7 22:01:54 2011 @@ -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 Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntry.java Fri Jan 7 22:01:54 2011 @@ -42,9 +42,10 @@ import org.apache.http.annotation.Immuta 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 S * 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 S 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 S 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" + Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializationException.java Fri Jan 7 22:01:54 2011 @@ -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; Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheEntrySerializer.java Fri Jan 7 22:01:54 2011 @@ -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; Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheStorage.java Fri Jan 7 22:01:54 2011 @@ -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; Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateCallback.java Fri Jan 7 22:01:54 2011 @@ -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 */ Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/HttpCacheUpdateException.java Fri Jan 7 22:01:54 2011 @@ -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 */ Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/InputLimit.java Fri Jan 7 22:01:54 2011 @@ -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; } Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/Resource.java Fri Jan 7 22:01:54 2011 @@ -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(); } Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java?rev=1056530&r1=1056529&r2=1056530&view=diff ============================================================================== --- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java (original) +++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/ResourceFactory.java Fri Jan 7 22:01:54 2011 @@ -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; }