You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by jo...@apache.org on 2011/01/07 23:01:54 UTC
svn commit: r1056530 -
/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/client/cache/
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<String, String> 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
* <code>null</code> if nonexistent
- * @return CacheEntry the cache entry that should replace it, again,
- * possible <code>null</code>
+ * @return HttpCacheEntry the cache entry that should replace it, again,
+ * possibly <code>null</code>
*
* @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;
}