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/10 17:33:51 UTC
svn commit: r1057265 - in
/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache:
CachingHttpClient.java package.html
Author: jonm
Date: Mon Jan 10 16:33:51 2011
New Revision: 1057265
URL: http://svn.apache.org/viewvc?rev=1057265&view=rev
Log:
Javadocs for CachingHttpClient itself.
Added:
httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html (with props)
Modified:
httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingHttpClient.java
Modified: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingHttpClient.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingHttpClient.java?rev=1057265&r1=1057264&r2=1057265&view=diff
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingHttpClient.java (original)
+++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/CachingHttpClient.java Mon Jan 10 16:33:51 2011
@@ -66,11 +66,52 @@ import org.apache.http.protocol.HttpCont
import org.apache.http.util.VersionInfo;
/**
+ * <p>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,
+ * though not all, of the SHOULDs and SHOULD NOTs are obeyed too. Generally
+ * speaking, you construct a {@code CachingHttpClient} by providing a
+ * "backend" {@link HttpClient} used for making actual network requests and
+ * provide an {@link HttpCacheStorage} instance to use for holding onto
+ * cached responses. Additional configuration options can be provided by
+ * 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.</p>
+ *
+ * <p>Generally speaking, the {@code CachingHttpClient} is implemented as a
+ * <a href="http://en.wikipedia.org/wiki/Decorator_pattern">Decorator</a>
+ * 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
+ * cache entry, it will use the backend client to make an actual request.
+ * However, a proper HTTP/1.1 cache won't change the semantics of a request
+ * and response; in particular, if you issue an unconditional request you
+ * will get a full response (although it may be served to you from the cache,
+ * 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.</p>
+ *
+ * <p>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.</p>
+ * </p>
* @since 4.1
*/
@ThreadSafe // So long as the responseCache implementation is threadsafe
public class CachingHttpClient implements HttpClient {
+ /**
+ * This is the name under which the {@link
+ * org.apache.http.client.cache.CacheResponseStatus} of a request
+ * (for example, whether it resulted in a cache hit) will be recorded if an
+ * {@link HttpContext} is provided during execution.
+ */
public static final String CACHE_RESPONSE_STATUS = "http.cache.response.status";
private final static boolean SUPPORTS_RANGE_AND_CONTENT_RANGE_HEADERS = false;
@@ -130,30 +171,64 @@ public class CachingHttpClient implement
this.asynchRevalidator = makeAsynchronousValidator(config);
}
+ /**
+ * Constructs a {@code CachingHttpClient} with default caching settings that
+ * stores cache entries in memory and uses a vanilla {@link DefaultHttpClient}
+ * for backend requests.
+ */
public CachingHttpClient() {
this(new DefaultHttpClient(),
new BasicHttpCache(),
new CacheConfig());
}
+ /**
+ * Constructs a {@code CachingHttpClient} with the given caching options that
+ * stores cache entries in memory and uses a vanilla {@link DefaultHttpClient}
+ * for backend requests.
+ * @param config cache module options
+ */
public CachingHttpClient(CacheConfig config) {
this(new DefaultHttpClient(),
new BasicHttpCache(config),
config);
}
+ /**
+ * Constructs a {@code CachingHttpClient} with default caching settings that
+ * stores cache entries in memory and uses the given {@link HttpClient}
+ * for backend requests.
+ * @param client used to make origin requests
+ */
public CachingHttpClient(HttpClient client) {
this(client,
new BasicHttpCache(),
new CacheConfig());
}
+ /**
+ * Constructs a {@code CachingHttpClient} with the given caching options that
+ * stores cache entries in memory and uses the given {@link HttpClient}
+ * for backend requests.
+ * @param config cache module options
+ * @param client used to make origin requests
+ */
public CachingHttpClient(HttpClient client, CacheConfig config) {
this(client,
new BasicHttpCache(config),
config);
}
+ /**
+ * Constructs a {@code CachingHttpClient} with the given caching options
+ * that stores cache entries in the provided storage backend and uses
+ * the given {@link HttpClient} for backend requests. However, cached
+ * response bodies are managed using the given {@link ResourceFactory}.
+ * @param client used to make origin requests
+ * @param resourceFactory how to manage cached response bodies
+ * @param storage where to store cache entries
+ * @param config cache module options
+ */
public CachingHttpClient(
HttpClient client,
ResourceFactory resourceFactory,
@@ -164,6 +239,14 @@ public class CachingHttpClient implement
config);
}
+ /**
+ * Constructs a {@code CachingHttpClient} with the given caching options
+ * that stores cache entries in the provided storage backend and uses
+ * the given {@link HttpClient} for backend requests.
+ * @param client used to make origin requests
+ * @param storage where to store cache entries
+ * @param config cache module options
+ */
public CachingHttpClient(
HttpClient client,
HttpCacheStorage storage,
@@ -209,167 +292,78 @@ public class CachingHttpClient implement
}
/**
- * Return the number of times that the cache successfully answered an HttpRequest
- * for a document of information from the server.
- *
- * @return long the number of cache successes
+ * Reports the number of times that the cache successfully responded
+ * to an {@link HttpRequest} without contacting the origin server.
+ * @return the number of cache hits
*/
public long getCacheHits() {
return cacheHits.get();
}
/**
- * Return the number of times that the cache was unable to answer an HttpRequest
- * for a document of information from the server.
- *
- * @return long the number of cache failures/misses
+ * Reports the number of times that the cache contacted the origin
+ * server because it had no appropriate response cached.
+ * @return the number of cache misses
*/
public long getCacheMisses() {
return cacheMisses.get();
}
/**
- * Return the number of times that the cache was able to revalidate
- * an existing cache entry for a document of information from the server.
- *
- * @return long the number of cache revalidations
+ * Reports the number of times that the cache was able to satisfy
+ * a response by revalidating an existing but stale cache entry.
+ * @return the number of cache revalidations
*/
public long getCacheUpdates() {
return cacheUpdates.get();
}
- /**
- * Execute an {@link HttpRequest} @ a given {@link HttpHost}
- *
- * @param target the target host for the request.
- * Implementations may accept <code>null</code>
- * if they can still determine a route, for example
- * to a default target or by inspecting the request.
- * @param request the request to execute
- * @return HttpResponse The cached entry or the result of a backend call
- * @throws IOException
- */
public HttpResponse execute(HttpHost target, HttpRequest request) throws IOException {
HttpContext defaultContext = null;
return execute(target, request, defaultContext);
}
- /**
- * Execute an {@link HttpRequest} @ a given {@link HttpHost} with a specified
- * {@link ResponseHandler} that will deal with the result of the call.
- *
- * @param target the target host for the request.
- * Implementations may accept <code>null</code>
- * if they can still determine a route, for example
- * to a default target or by inspecting the request.
- * @param request the request to execute
- * @param responseHandler the response handler
- * @param <T> The Return Type Identified by the generic type of the {@link ResponseHandler}
- * @return T The response type as handled by ResponseHandler
- * @throws IOException
- */
public <T> T execute(HttpHost target, HttpRequest request,
ResponseHandler<? extends T> responseHandler) throws IOException {
return execute(target, request, responseHandler, null);
}
- /**
- * Execute an {@link HttpRequest} @ a given {@link HttpHost} with a specified
- * {@link ResponseHandler} that will deal with the result of the call using
- * a specific {@link HttpContext}
- *
- * @param target the target host for the request.
- * Implementations may accept <code>null</code>
- * if they can still determine a route, for example
- * to a default target or by inspecting the request.
- * @param request the request to execute
- * @param responseHandler the response handler
- * @param context the context to use for the execution, or
- * <code>null</code> to use the default context
- * @param <T> The Return Type Identified by the generic type of the {@link ResponseHandler}
- * @return T The response type as handled by ResponseHandler
- * @throws IOException
- */
public <T> T execute(HttpHost target, HttpRequest request,
ResponseHandler<? extends T> responseHandler, HttpContext context) throws IOException {
HttpResponse resp = execute(target, request, context);
return responseHandler.handleResponse(resp);
}
- /**
- * @param request the request to execute
- * @return HttpResponse The cached entry or the result of a backend call
- * @throws IOException
- */
public HttpResponse execute(HttpUriRequest request) throws IOException {
HttpContext context = null;
return execute(request, context);
}
- /**
- * @param request the request to execute
- * @param context the context to use for the execution, or
- * <code>null</code> to use the default context
- * @return HttpResponse The cached entry or the result of a backend call
- * @throws IOException
- */
public HttpResponse execute(HttpUriRequest request, HttpContext context) throws IOException {
URI uri = request.getURI();
HttpHost httpHost = new HttpHost(uri.getHost(), uri.getPort(), uri.getScheme());
return execute(httpHost, request, context);
}
- /**
- * @param request the request to execute
- * @param responseHandler the response handler
- * @param <T> The Return Type Identified by the generic type of the {@link ResponseHandler}
- * @return T The response type as handled by ResponseHandler
- * @throws IOException
- */
public <T> T execute(HttpUriRequest request, ResponseHandler<? extends T> responseHandler)
throws IOException {
return execute(request, responseHandler, null);
}
- /**
- * @param request the request to execute
- * @param responseHandler the response handler
- * @param context the http context
- * @param <T> The Return Type Identified by the generic type of the {@link ResponseHandler}
- * @return T The response type as handled by ResponseHandler
- * @throws IOException
- */
public <T> T execute(HttpUriRequest request, ResponseHandler<? extends T> responseHandler,
HttpContext context) throws IOException {
HttpResponse resp = execute(request, context);
return responseHandler.handleResponse(resp);
}
- /**
- * @return the connection manager
- */
public ClientConnectionManager getConnectionManager() {
return backend.getConnectionManager();
}
- /**
- * @return the parameters
- */
public HttpParams getParams() {
return backend.getParams();
}
- /**
- * @param target the target host for the request.
- * Implementations may accept <code>null</code>
- * if they can still determine a route, for example
- * to a default target or by inspecting the request.
- * @param request the request to execute
- * @param context the context to use for the execution, or
- * <code>null</code> to use the default context
- * @return the response
- * @throws IOException
- */
public HttpResponse execute(HttpHost target, HttpRequest request, HttpContext context)
throws IOException {
@@ -626,10 +620,23 @@ public class CachingHttpClient implement
}
}
+ /**
+ * Reports whether this {@code CachingHttpClient} implementation
+ * supports byte-range requests as specified by the {@code Range}
+ * and {@code Content-Range} headers.
+ * @return {@code true} if byte-range requests are supported
+ */
public boolean supportsRangeAndContentRangeHeaders() {
return SUPPORTS_RANGE_AND_CONTENT_RANGE_HEADERS;
}
+ /**
+ * Reports whether this {@code CachingHttpClient} is configured as
+ * a shared (public) or non-shared (private) cache. See {@link
+ * CacheConfig#setSharedCache(boolean)}.
+ * @return {@code true} if we are behaving as a shared (public)
+ * cache
+ */
public boolean isSharedCache() {
return sharedCache;
}
Added: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html?rev=1057265&view=auto
==============================================================================
--- httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html (added)
+++ httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html Mon Jan 10 16:33:51 2011
@@ -0,0 +1,42 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+====================================================================
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+====================================================================
+
+This software consists of voluntary contributions made by many
+individuals on behalf of the Apache Software Foundation. For more
+information on the Apache Software Foundation, please see
+<http://www.apache.org/>.
+-->
+</head>
+<body bgcolor="white">
+
+<p>
+This package contains a cache module that can be used for HTTP/1.1
+client-side caching. The primary classes in this package are the
+{@link org.apache.http.impl.client.cache.CachingHttpClient},
+which is a drop-in replacement for
+a {@link org.apache.http.impl.client.DefaultHttpClient} that adds
+caching, and the {@link org.apache.http.impl.client.cache.CacheConfig}
+class that can be used for configuring it.
+</p>
+</body>
+</html>
Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: httpcomponents/httpclient/trunk/httpclient-cache/src/main/java/org/apache/http/impl/client/cache/package.html
------------------------------------------------------------------------------
svn:mime-type = text/html