Package net.shibboleth.shared.httpclient

# Class FileCachingHttpClientBuilder

java.lang.Object
net.shibboleth.shared.httpclient.HttpClientBuilder
net.shibboleth.shared.httpclient.FileCachingHttpClientBuilder

Direct Known Subclasses:
  `FileCachingHttpClientFactoryBean`

public class FileCachingHttpClientBuilder extends HttpClientBuilder
An `HttpClient` builder that supports RFC 2616 caching.

Cached content is written to disk. Special care should be taken so that multiple clients do not share a single cache directory unintentionally. This could result in sensitive data being available in ways it should not be.

When using the single-arg constructor variant to wrap an existing instance of `CachingHttpClientBuilder`, there are several caveats of which to be aware:

- Several important non-caching-specific caveats are enumerated in this class's superclass `HttpClientBuilder`.
- Instances of the following which are set as the default instance on the Apache builder will be unconditionally overwritten by this builder when `buildClient()` is called:
  - `CacheConfig`

  This is due to the unfortunate fact that the Apache builder does not currently provide accessor methods to obtain the default instances currently set on the builder. Therefore, if you need to set any default cache config parameters which are not exposed by this builder, then you must use the Apache builder directly and may not use this builder.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`private static class`
`FileCachingHttpClientBuilder.StorageMaintenanceTask`
Scheduled task to manage an instance of `ManagedHttpCacheStorage`.
`private static class`
`FileCachingHttpClientBuilder.StorageManagingHttpClient`
Class which wraps a caching instance of `HttpClient` and its associated `ManagedHttpCacheStorage`, and manages the scheduled maintenance and lifecycle of the latter.

## Field Summary

Fields
Modifier and Type
Field
Description
`private File`
`cacheDir`
Directory in which cached content will be stored.
`private Duration`
`maintentanceTaskInterval`
Interval at which the storage maintenance task should run.
`private org.apache.hc.client5.http.impl.cache.ManagedHttpCacheStorage`
`managedStorage`
The current managed storage instance.
`private int`
`maxCacheEntries`
The maximum number of cached responses.
`private long`
`maxCacheEntrySize`
The maximum response body size, in bytes, that will be eligible for caching.

## Constructor Summary

Constructors
Constructor
Description
`FileCachingHttpClientBuilder()`
Constructor.
`FileCachingHttpClientBuilder(org.apache.hc.client5.http.impl.cache.CachingHttpClientBuilder builder)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`org.apache.hc.client5.http.classic.HttpClient`
`buildClient()`
Constructs an `HttpClient` using the settings of this builder.
`protected void`
`decorateApacheBuilder()`
Decorate the Apache builder as determined by this builder's parameters.
`File`
`getCacheDirectory()`
Gets the directory in which cached content will be stored.
`Duration`
`getMaintentanceTaskInterval()`
Get the interval at which the storage maintenance task should run.
`int`
`getMaxCacheEntries()`
Gets the maximum number of cached responses.
`long`
`getMaxCacheEntrySize()`
Gets the maximum response body size, in bytes, that will be eligible for caching.
`void`
`setCacheDirectory(File directory)`
Sets the directory in which cached content will be stored.
`void`
`setCacheDirectory(String directoryPath)`
Sets the directory in which cached content will be stored.
`void`
`setMaintentanceTaskInterval(Duration value)`
Set the interval at which the storage maintenance task should run.
`void`
`setMaxCacheEntries(int maxEntries)`
Sets the maximum number of cached responses.
`void`
`setMaxCacheEntrySize(long size)`
Sets the maximum response body size, in bytes, that will be eligible for caching.

### Methods inherited from class net.shibboleth.shared.httpclient.HttpClientBuilder

`buildConnectionFactory, buildConnectionManager, buildDefaultConnectionConfig, buildDefaultCredentialsProvider, buildDefaultRequestConfig, buildRoutePlanner, getApacheBuilder, getConnectionMaxIdleTime, getConnectionProxyHost, getConnectionProxyPassword, getConnectionProxyPort, getConnectionProxyUsername, getConnectionRequestTimeout, getConnectionTimeout, getFirstRequestInterceptors, getFirstResponseInterceptors, getHttpContentCharSet, getHttpRequestRetryStrategy, getLastRequestInterceptors, getLastResponseInterceptors, getMaxConnectionsPerRoute, getMaxConnectionsTotal, getRequestTimeout, getRequestTimeoutCorePoolSize, getResponseTimeout, getSchemePortResolver, getSocketBufferSize, getSocketLocalAddress, getSocketTimeout, getStaticContextHandlers, getTLSSocketFactory, getUserAgent, getValidateAfterInactivity, handleFluentProperties, isConnectionCloseAfterResponse, isConnectionDisregardTLSCertificate, isDisableAuthCaching, isDisableAutomaticRetries, isDisableConnectionState, isDisableContentCompression, isDisableCookieManagement, isDisableRedirectHandling, isEvictExpiredConnections, isEvictIdleConnections, isHttpFollowRedirects, isUseSystemProperties, resetDefaults, setConnectionCloseAfterResponse, setConnectionDisregardTLSCertificate, setConnectionMaxIdleTime, setConnectionProxyHost, setConnectionProxyPassword, setConnectionProxyPort, setConnectionProxyUsername, setConnectionRequestTimeout, setConnectionTimeout, setDisableAuthCaching, setDisableAutomaticRetries, setDisableConnectionState, setDisableContentCompression, setDisableCookieManagement, setDisableRedirectHandling, setEvictExpiredConnections, setEvictIdleConnections, setFirstRequestInterceptors, setFirstResponseInterceptors, setHttpContentCharSet, setHttpFollowRedirects, setHttpRequestRetryStrategy, setLastRequestInterceptors, setLastResponseInterceptors, setMaxConnectionsPerRoute, setMaxConnectionsTotal, setRequestTimeout, setRequestTimeoutCorePoolSize, setResponseTimeout, setSchemePortResolver, setSocketBufferSize, setSocketLocalAddress, setSocketLocalAddress, setSocketTimeout, setStaticContextHandlers, setTLSSocketFactory, setUserAgent, setUseSystemProperties, setValidateAfterInactivity`

### Methods inherited from class java.lang.Object

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

## Field Details

### cacheDir

@Nonnull private File cacheDir
Directory in which cached content will be stored. Default: `System.getProperty("java.io.tmpdir") + File.separator + "wwwcache"`

### maxCacheEntries

private int maxCacheEntries
The maximum number of cached responses. Default: 100

### maxCacheEntrySize

private long maxCacheEntrySize
The maximum response body size, in bytes, that will be eligible for caching. Default: 10485760 (10 megabytes)

### maintentanceTaskInterval

@Nonnull private Duration maintentanceTaskInterval
Interval at which the storage maintenance task should run.

### managedStorage

private org.apache.hc.client5.http.impl.cache.ManagedHttpCacheStorage managedStorage
The current managed storage instance.

## Constructor Details

### FileCachingHttpClientBuilder

public FileCachingHttpClientBuilder()
Constructor.

### FileCachingHttpClientBuilder

public FileCachingHttpClientBuilder(@Nonnull org.apache.hc.client5.http.impl.cache.CachingHttpClientBuilder builder)
Constructor.

Parameters:
  `builder` - builder of clients used to fetch data from remote servers

## Method Details

### getCacheDirectory

public File getCacheDirectory()
Gets the directory in which cached content will be stored.

Returns:
  directory in which cached content will be stored

### setCacheDirectory

public void setCacheDirectory(@Nonnull @NotEmpty String directoryPath)
Sets the directory in which cached content will be stored.

Parameters:
  `directoryPath` - filesystem path to the directory

### setCacheDirectory

public void setCacheDirectory(@Nonnull File directory)
Sets the directory in which cached content will be stored.

Parameters:
  `directory` - the directory

### getMaxCacheEntries

public int getMaxCacheEntries()
Gets the maximum number of cached responses.

Returns:
  maximum number of cached responses

### setMaxCacheEntries

public void setMaxCacheEntries(int maxEntries)
Sets the maximum number of cached responses.

Parameters:
  `maxEntries` - maximum number of cached responses, must be greater than zero

### getMaxCacheEntrySize

public long getMaxCacheEntrySize()
Gets the maximum response body size, in bytes, that will be eligible for caching.

Returns:
  maximum response body size that will be eligible for caching

### setMaxCacheEntrySize

public void setMaxCacheEntrySize(long size)
Sets the maximum response body size, in bytes, that will be eligible for caching.

Parameters:
  `size` - maximum response body size that will be eligible for caching, must be greater than zero

### getMaintentanceTaskInterval

@Nonnull public Duration getMaintentanceTaskInterval()
Get the interval at which the storage maintenance task should run.

Returns:
  the maintenance task interval

### setMaintentanceTaskInterval

public void setMaintentanceTaskInterval(@Nonnull Duration value)
Set the interval at which the storage maintenance task should run.

Parameters:
  `value` - the new maintenance task interval

### decorateApacheBuilder

protected void decorateApacheBuilder() throws Exception
Decorate the Apache builder as determined by this builder's parameters. Subclasses will likely add additional decoration.

Overrides:
  `decorateApacheBuilder` in class `HttpClientBuilder`
Throws:
  `Exception` - if there is a problem decorating the Apache builder

### buildClient

@Nonnull public org.apache.hc.client5.http.classic.HttpClient buildClient() throws Exception
Constructs an `HttpClient` using the settings of this builder.

Overrides:
  `buildClient` in class `HttpClientBuilder`
Returns:
  the constructed client
Throws:
  `Exception` - if there is any problem building the new client instance