Package org.apache.http.impl.client.cache

Class CachingExec

java.lang.Object

org.apache.http.impl.client.cache.CachingExec

All Implemented Interfaces:

ClientExecChain

@Contract(threading=SAFE_CONDITIONAL)
public class CachingExec
extends java.lang.Object
implements ClientExecChain

Request executor in the request execution chain that is responsible for transparent 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.

Folks that would like to experiment with alternative storage backends should look at the HttpCacheStorage interface and the related package documentation there. You may also be interested in the provided EhCache and memcached storage backends.

Further responsibilities such as communication with the opposite endpoint is delegated to the next executor in the request execution chain.

Since:

4.3

Field Summary

Fields

Modifier and Type	Field	Description
private AsynchronousValidator	asynchRevalidator
private ClientExecChain	backend
private CacheableRequestPolicy	cacheableRequestPolicy
private CacheConfig	cacheConfig
private java.util.concurrent.atomic.AtomicLong	cacheHits
private java.util.concurrent.atomic.AtomicLong	cacheMisses
private java.util.concurrent.atomic.AtomicLong	cacheUpdates
private ConditionalRequestBuilder	conditionalRequestBuilder
private org.apache.commons.logging.Log	log
private RequestProtocolCompliance	requestCompliance
private HttpCache	responseCache
private ResponseCachingPolicy	responseCachingPolicy
private ResponseProtocolCompliance	responseCompliance
private CachedHttpResponseGenerator	responseGenerator
private CachedResponseSuitabilityChecker	suitabilityChecker
private static boolean	SUPPORTS_RANGE_AND_CONTENT_RANGE_HEADERS
private CacheValidityPolicy	validityPolicy
private java.util.Map<org.apache.http.ProtocolVersion,java.lang.String>	viaHeaders

Constructor Summary

Constructors

Constructor	Description
CachingExec(ClientExecChain backend)
CachingExec(ClientExecChain backend, ResourceFactory resourceFactory, HttpCacheStorage storage, CacheConfig config)
CachingExec(ClientExecChain backend, HttpCache cache, CacheConfig config)
CachingExec(ClientExecChain backend, HttpCache cache, CacheConfig config, AsynchronousValidator asynchRevalidator)
CachingExec(ClientExecChain backend, HttpCache responseCache, CacheValidityPolicy validityPolicy, ResponseCachingPolicy responseCachingPolicy, CachedHttpResponseGenerator responseGenerator, CacheableRequestPolicy cacheableRequestPolicy, CachedResponseSuitabilityChecker suitabilityChecker, ConditionalRequestBuilder conditionalRequestBuilder, ResponseProtocolCompliance responseCompliance, RequestProtocolCompliance requestCompliance, CacheConfig config, AsynchronousValidator asynchRevalidator)

Method Summary

Modifier and Type	Method	Description
private boolean	alreadyHaveNewerCacheEntry(org.apache.http.HttpHost target, HttpRequestWrapper request, org.apache.http.HttpResponse backendResponse)
(package private) CloseableHttpResponse	callBackend(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware)
(package private) boolean	clientRequestsOurOptions(org.apache.http.HttpRequest request)
CloseableHttpResponse	execute(HttpRoute route, HttpRequestWrapper request)
CloseableHttpResponse	execute(HttpRoute route, HttpRequestWrapper request, HttpClientContext context)
CloseableHttpResponse	execute(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware)	Executes th request either by transmitting it to the target server or by passing it onto the next executor in the request execution chain.
private boolean	explicitFreshnessRequest(HttpRequestWrapper request, HttpCacheEntry entry, java.util.Date now)
private void	flushEntriesInvalidatedByRequest(org.apache.http.HttpHost target, HttpRequestWrapper request)
private CloseableHttpResponse	generateCachedResponse(HttpRequestWrapper request, org.apache.http.protocol.HttpContext context, HttpCacheEntry entry, java.util.Date now)
private CloseableHttpResponse	generateGatewayTimeout(org.apache.http.protocol.HttpContext context)
private java.lang.String	generateViaHeader(org.apache.http.HttpMessage msg)
long	getCacheHits()	Reports the number of times that the cache successfully responded to an HttpRequest without contacting the origin server.
long	getCacheMisses()	Reports the number of times that the cache contacted the origin server because it had no appropriate response cached.
long	getCacheUpdates()	Reports the number of times that the cache was able to satisfy a response by revalidating an existing but stale cache entry.
(package private) java.util.Date	getCurrentDate()
private java.util.Map<java.lang.String,Variant>	getExistingCacheVariants(org.apache.http.HttpHost target, HttpRequestWrapper request)
private org.apache.http.HttpResponse	getFatallyNoncompliantResponse(HttpRequestWrapper request, org.apache.http.protocol.HttpContext context)
private HttpCacheEntry	getUpdatedVariantEntry(org.apache.http.HttpHost target, HttpRequestWrapper conditionalRequest, java.util.Date requestDate, java.util.Date responseDate, CloseableHttpResponse backendResponse, Variant matchingVariant, HttpCacheEntry matchedEntry)
(package private) CloseableHttpResponse	handleBackendResponse(HttpRequestWrapper request, HttpClientContext context, java.util.Date requestDate, java.util.Date responseDate, CloseableHttpResponse backendResponse)
private CloseableHttpResponse	handleCacheHit(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware, HttpCacheEntry entry)
private CloseableHttpResponse	handleCacheMiss(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware)
private CloseableHttpResponse	handleRevalidationFailure(HttpRequestWrapper request, org.apache.http.protocol.HttpContext context, HttpCacheEntry entry, java.util.Date now)
private boolean	mayCallBackend(HttpRequestWrapper request)
(package private) CloseableHttpResponse	negotiateResponseFromVariants(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware, java.util.Map<java.lang.String,Variant> variants)
private void	recordCacheHit(org.apache.http.HttpHost target, HttpRequestWrapper request)
private void	recordCacheMiss(org.apache.http.HttpHost target, HttpRequestWrapper request)
private void	recordCacheUpdate(org.apache.http.protocol.HttpContext context)
private CloseableHttpResponse	retryRequestUnconditionally(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware, HttpCacheEntry matchedEntry)
(package private) CloseableHttpResponse	revalidateCacheEntry(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware, HttpCacheEntry cacheEntry)
private CloseableHttpResponse	revalidateCacheEntry(HttpRoute route, HttpRequestWrapper request, HttpClientContext context, HttpExecutionAware execAware, HttpCacheEntry entry, java.util.Date now)
private boolean	revalidationResponseIsTooOld(org.apache.http.HttpResponse backendResponse, HttpCacheEntry cacheEntry)
private HttpCacheEntry	satisfyFromCache(org.apache.http.HttpHost target, HttpRequestWrapper request)
private void	setResponseStatus(org.apache.http.protocol.HttpContext context, CacheResponseStatus value)
private boolean	shouldSendNotModifiedResponse(HttpRequestWrapper request, HttpCacheEntry responseEntry)
private boolean	staleIfErrorAppliesTo(int statusCode)
private boolean	staleResponseNotAllowed(HttpRequestWrapper request, HttpCacheEntry entry, java.util.Date now)
private void	storeRequestIfModifiedSinceFor304Response(org.apache.http.HttpRequest request, org.apache.http.HttpResponse backendResponse)	For 304 Not modified responses, adds a "Last-Modified" header with the value of the "If-Modified-Since" header passed in the request.
boolean	supportsRangeAndContentRangeHeaders()	Reports whether this CachingHttpClient implementation supports byte-range requests as specified by the Range and Content-Range headers.
private void	tryToUpdateVariantMap(org.apache.http.HttpHost target, HttpRequestWrapper request, Variant matchingVariant)
private CloseableHttpResponse	unvalidatedCacheHit(HttpRequestWrapper request, org.apache.http.protocol.HttpContext context, HttpCacheEntry entry)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SUPPORTS_RANGE_AND_CONTENT_RANGE_HEADERS

private static final boolean SUPPORTS_RANGE_AND_CONTENT_RANGE_HEADERS

See Also:

Constant Field Values

cacheHits

private final java.util.concurrent.atomic.AtomicLong cacheHits

cacheMisses

private final java.util.concurrent.atomic.AtomicLong cacheMisses

cacheUpdates

private final java.util.concurrent.atomic.AtomicLong cacheUpdates

viaHeaders

private final java.util.Map<org.apache.http.ProtocolVersion,java.lang.String> viaHeaders

cacheConfig

private final CacheConfig cacheConfig

backend

private final ClientExecChain backend

responseCache

private final HttpCache responseCache

validityPolicy

private final CacheValidityPolicy validityPolicy

responseGenerator

private final CachedHttpResponseGenerator responseGenerator

cacheableRequestPolicy

private final CacheableRequestPolicy cacheableRequestPolicy

suitabilityChecker

private final CachedResponseSuitabilityChecker suitabilityChecker

conditionalRequestBuilder

private final ConditionalRequestBuilder conditionalRequestBuilder

responseCompliance

private final ResponseProtocolCompliance responseCompliance

requestCompliance

private final RequestProtocolCompliance requestCompliance

responseCachingPolicy

private final ResponseCachingPolicy responseCachingPolicy

asynchRevalidator

private final AsynchronousValidator asynchRevalidator

log

private final org.apache.commons.logging.Log log

Constructor Detail

CachingExec

public CachingExec(ClientExecChain backend,
                   HttpCache cache,
                   CacheConfig config)

CachingExec

public CachingExec(ClientExecChain backend,
                   HttpCache cache,
                   CacheConfig config,
                   AsynchronousValidator asynchRevalidator)

CachingExec

public CachingExec(ClientExecChain backend,
                   ResourceFactory resourceFactory,
                   HttpCacheStorage storage,
                   CacheConfig config)

CachingExec

public CachingExec(ClientExecChain backend)

CachingExec

CachingExec(ClientExecChain backend,
            HttpCache responseCache,
            CacheValidityPolicy validityPolicy,
            ResponseCachingPolicy responseCachingPolicy,
            CachedHttpResponseGenerator responseGenerator,
            CacheableRequestPolicy cacheableRequestPolicy,
            CachedResponseSuitabilityChecker suitabilityChecker,
            ConditionalRequestBuilder conditionalRequestBuilder,
            ResponseProtocolCompliance responseCompliance,
            RequestProtocolCompliance requestCompliance,
            CacheConfig config,
            AsynchronousValidator asynchRevalidator)

Method Detail

getCacheHits

public long getCacheHits()

Reports the number of times that the cache successfully responded to an HttpRequest without contacting the origin server.

Returns:

the number of cache hits

getCacheMisses

public long getCacheMisses()

Reports the number of times that the cache contacted the origin server because it had no appropriate response cached.

Returns:

the number of cache misses

getCacheUpdates

public long getCacheUpdates()

Reports the number of times that the cache was able to satisfy a response by revalidating an existing but stale cache entry.

Returns:

the number of cache revalidations

execute

public CloseableHttpResponse execute(HttpRoute route,
                                     HttpRequestWrapper request)
                              throws java.io.IOException,
                                     org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

execute

public CloseableHttpResponse execute(HttpRoute route,
                                     HttpRequestWrapper request,
                                     HttpClientContext context)
                              throws java.io.IOException,
                                     org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

execute

public CloseableHttpResponse execute(HttpRoute route,
                                     HttpRequestWrapper request,
                                     HttpClientContext context,
                                     HttpExecutionAware execAware)
                              throws java.io.IOException,
                                     org.apache.http.HttpException

Description copied from interface: ClientExecChain

Executes th request either by transmitting it to the target server or by passing it onto the next executor in the request execution chain.

Specified by:

execute in interface ClientExecChain

Parameters:

route - connection route.

request - current request.

context - current HTTP context.

execAware - receiver of notifications of blocking I/O operations.

Returns:

HTTP response either received from the opposite endpoint or generated locally.

Throws:

java.io.IOException - in case of a I/O error. (this type of exceptions are potentially recoverable).

org.apache.http.HttpException - in case of an HTTP protocol error (usually this type of exceptions are non-recoverable).

handleCacheHit

private CloseableHttpResponse handleCacheHit(HttpRoute route,
                                             HttpRequestWrapper request,
                                             HttpClientContext context,
                                             HttpExecutionAware execAware,
                                             HttpCacheEntry entry)
                                      throws java.io.IOException,
                                             org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

revalidateCacheEntry

private CloseableHttpResponse revalidateCacheEntry(HttpRoute route,
                                                   HttpRequestWrapper request,
                                                   HttpClientContext context,
                                                   HttpExecutionAware execAware,
                                                   HttpCacheEntry entry,
                                                   java.util.Date now)
                                            throws org.apache.http.HttpException

Throws:

org.apache.http.HttpException

handleCacheMiss

private CloseableHttpResponse handleCacheMiss(HttpRoute route,
                                              HttpRequestWrapper request,
                                              HttpClientContext context,
                                              HttpExecutionAware execAware)
                                       throws java.io.IOException,
                                              org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

satisfyFromCache

private HttpCacheEntry satisfyFromCache(org.apache.http.HttpHost target,
                                        HttpRequestWrapper request)

getFatallyNoncompliantResponse

private org.apache.http.HttpResponse getFatallyNoncompliantResponse(HttpRequestWrapper request,
                                                                    org.apache.http.protocol.HttpContext context)

getExistingCacheVariants

private java.util.Map<java.lang.String,Variant> getExistingCacheVariants(org.apache.http.HttpHost target,
                                                                               HttpRequestWrapper request)

recordCacheMiss

private void recordCacheMiss(org.apache.http.HttpHost target,
                             HttpRequestWrapper request)

recordCacheHit

private void recordCacheHit(org.apache.http.HttpHost target,
                            HttpRequestWrapper request)

recordCacheUpdate

private void recordCacheUpdate(org.apache.http.protocol.HttpContext context)

flushEntriesInvalidatedByRequest

private void flushEntriesInvalidatedByRequest(org.apache.http.HttpHost target,
                                              HttpRequestWrapper request)

generateCachedResponse

private CloseableHttpResponse generateCachedResponse(HttpRequestWrapper request,
                                                     org.apache.http.protocol.HttpContext context,
                                                     HttpCacheEntry entry,
                                                     java.util.Date now)

handleRevalidationFailure

private CloseableHttpResponse handleRevalidationFailure(HttpRequestWrapper request,
                                                        org.apache.http.protocol.HttpContext context,
                                                        HttpCacheEntry entry,
                                                        java.util.Date now)

generateGatewayTimeout

private CloseableHttpResponse generateGatewayTimeout(org.apache.http.protocol.HttpContext context)

unvalidatedCacheHit

private CloseableHttpResponse unvalidatedCacheHit(HttpRequestWrapper request,
                                                  org.apache.http.protocol.HttpContext context,
                                                  HttpCacheEntry entry)

staleResponseNotAllowed

private boolean staleResponseNotAllowed(HttpRequestWrapper request,
                                        HttpCacheEntry entry,
                                        java.util.Date now)

mayCallBackend

private boolean mayCallBackend(HttpRequestWrapper request)

explicitFreshnessRequest

private boolean explicitFreshnessRequest(HttpRequestWrapper request,
                                         HttpCacheEntry entry,
                                         java.util.Date now)

generateViaHeader

private java.lang.String generateViaHeader(org.apache.http.HttpMessage msg)

setResponseStatus

private void setResponseStatus(org.apache.http.protocol.HttpContext context,
                               CacheResponseStatus value)

supportsRangeAndContentRangeHeaders

public boolean supportsRangeAndContentRangeHeaders()

Reports whether this CachingHttpClient implementation supports byte-range requests as specified by the Range and Content-Range headers.

Returns:

true if byte-range requests are supported

getCurrentDate

java.util.Date getCurrentDate()

clientRequestsOurOptions

boolean clientRequestsOurOptions(org.apache.http.HttpRequest request)

callBackend

CloseableHttpResponse callBackend(HttpRoute route,
                                  HttpRequestWrapper request,
                                  HttpClientContext context,
                                  HttpExecutionAware execAware)
                           throws java.io.IOException,
                                  org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

revalidationResponseIsTooOld

private boolean revalidationResponseIsTooOld(org.apache.http.HttpResponse backendResponse,
                                             HttpCacheEntry cacheEntry)

negotiateResponseFromVariants

CloseableHttpResponse negotiateResponseFromVariants(HttpRoute route,
                                                    HttpRequestWrapper request,
                                                    HttpClientContext context,
                                                    HttpExecutionAware execAware,
                                                    java.util.Map<java.lang.String,Variant> variants)
                                             throws java.io.IOException,
                                                    org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

retryRequestUnconditionally

private CloseableHttpResponse retryRequestUnconditionally(HttpRoute route,
                                                          HttpRequestWrapper request,
                                                          HttpClientContext context,
                                                          HttpExecutionAware execAware,
                                                          HttpCacheEntry matchedEntry)
                                                   throws java.io.IOException,
                                                          org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

getUpdatedVariantEntry

private HttpCacheEntry getUpdatedVariantEntry(org.apache.http.HttpHost target,
                                              HttpRequestWrapper conditionalRequest,
                                              java.util.Date requestDate,
                                              java.util.Date responseDate,
                                              CloseableHttpResponse backendResponse,
                                              Variant matchingVariant,
                                              HttpCacheEntry matchedEntry)
                                       throws java.io.IOException

Throws:

java.io.IOException

tryToUpdateVariantMap

private void tryToUpdateVariantMap(org.apache.http.HttpHost target,
                                   HttpRequestWrapper request,
                                   Variant matchingVariant)

shouldSendNotModifiedResponse

private boolean shouldSendNotModifiedResponse(HttpRequestWrapper request,
                                              HttpCacheEntry responseEntry)

revalidateCacheEntry

CloseableHttpResponse revalidateCacheEntry(HttpRoute route,
                                           HttpRequestWrapper request,
                                           HttpClientContext context,
                                           HttpExecutionAware execAware,
                                           HttpCacheEntry cacheEntry)
                                    throws java.io.IOException,
                                           org.apache.http.HttpException

Throws:

java.io.IOException

org.apache.http.HttpException

staleIfErrorAppliesTo

private boolean staleIfErrorAppliesTo(int statusCode)

handleBackendResponse

CloseableHttpResponse handleBackendResponse(HttpRequestWrapper request,
                                            HttpClientContext context,
                                            java.util.Date requestDate,
                                            java.util.Date responseDate,
                                            CloseableHttpResponse backendResponse)
                                     throws java.io.IOException

Throws:

java.io.IOException

storeRequestIfModifiedSinceFor304Response

private void storeRequestIfModifiedSinceFor304Response(org.apache.http.HttpRequest request,
                                                       org.apache.http.HttpResponse backendResponse)

For 304 Not modified responses, adds a "Last-Modified" header with the value of the "If-Modified-Since" header passed in the request. This header is required to be able to reuse match the cache entry for subsequent requests but as defined in http specifications it is not included in 304 responses by backend servers. This header will not be included in the resulting response.

alreadyHaveNewerCacheEntry

private boolean alreadyHaveNewerCacheEntry(org.apache.http.HttpHost target,
                                           HttpRequestWrapper request,
                                           org.apache.http.HttpResponse backendResponse)