Package net.shibboleth.shared.spring.httpclient.resource

# Class HTTPResource

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent
net.shibboleth.shared.spring.httpclient.resource.HTTPResource

All Implemented Interfaces:
  `Component`, `DestructableComponent`, `IdentifiedComponent`, `InitializableComponent`, `Resource`, `Aware`, `BeanNameAware`, `InitializingBean`, `InputStreamSource`, `Resource`

Direct Known Subclasses:
  `FileBackedHTTPResource`

public class HTTPResource extends AbstractIdentifiedInitializableComponent implements Resource, BeanNameAware, InitializingBean, Resource
Resource for looking up HTTP URLs. Allows injection and therefore configuration of an Apache `HttpClient`. Code based on OpenSAML `HTTPMetadataResolver` and `UrlResource`.

## Field Summary

Fields
Modifier and Type
Field
Description
`private final org.apache.hc.client5.http.classic.HttpClient`
`httpClient`
HTTP Client used to pull the resource.
`private HttpClientContextHandler`
`httpClientContextHandler`
Optional handler to pre- and post-process context.
`private final org.slf4j.Logger`
`log`
Class logger.
`private final URL`
`resourceURL`
URL to the Resource.

## Constructor Summary

Constructors
Constructor
Description
`HTTPResource(org.apache.hc.client5.http.classic.HttpClient client, String url)`
Constructor.
`HTTPResource(org.apache.hc.client5.http.classic.HttpClient client, URL url)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`void`
`afterPropertiesSet()`
`protected org.apache.hc.client5.http.cache.HttpCacheContext`
`buildHttpClientContext()`
Build the `HttpCacheContext` instance which will be used to invoke the `HttpClient` request.
`protected void`
`closeResponse(org.apache.hc.core5.http.ClassicHttpResponse response)`
Close the HTTP response.
`long`
`contentLength()`
Determine the content length for this resource.
`HTTPResource`
`createRelative(String relativePath)`
Based on `UrlResource`.
`HTTPResource`
`createRelative(String relativePath, HttpClientContextHandler handler)`
Create a resource relative to us, but use the supplied handler.
`Resource`
`createRelativeResource(String relativePath)`
Create a resource relative to this resource.
`boolean`
`exists()`
Return whether this resource actually exists in physical form.
`String`
`getDescription()`
Return a description for this resource, to be used for error output when working with the resource.
`File`
`getFile()`
Return a File handle for this resource.
`String`
`getFilename()`
Determine a filename for this resource, i.e.
`InputStream`
`getInputStream()`
Return an `InputStream`.
`protected org.apache.hc.core5.http.HttpResponse`
`getResourceHeaders()`
Attempts to fetch only the headers for a given resource.
`protected String`
`getResponseHeader(String what)`
Send a Head to the client and interrogate the response for a particular response header.
`URI`
`getURI()`
Return a URI handle for this resource.
`URL`
`getURL()`
Return a URL handle for this resource.
`boolean`
`isFile()`
Determine whether this resource represents a file in a file system.
`boolean`
`isOpen()`
Return whether this resource represents a handle with an open stream.
`boolean`
`isReadable()`
Return whether the contents of this resource can be read, e.g.
`long`
`lastModified()`
Determine the last-modified timestamp for this resource.
`protected void`
`reportCachingStatus(org.apache.hc.client5.http.cache.HttpCacheContext context)`
Print out to the log whether we hit the apache cache or not.
`void`
`setBeanName(String name)`
`void`
`setHttpClientContextHandler(HttpClientContextHandler handler)`
Set a handler to manipulate the `HttpClientContext`.

### Methods inherited from class net.shibboleth.shared.component.AbstractIdentifiedInitializableComponent

`doInitialize, ensureId, getId, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException, setId`

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, doDestroy, initialize, isDestroyed, isInitialized`

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

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

### Methods inherited from interface org.springframework.core.io.Resource

`getContentAsByteArray, getContentAsString, getFilePath, readableChannel`

## Field Details

### log

@Nonnull private final org.slf4j.Logger log
Class logger.

### httpClient

@Nonnull private final org.apache.hc.client5.http.classic.HttpClient httpClient
HTTP Client used to pull the resource.

### resourceURL

@Nonnull private final URL resourceURL
URL to the Resource.

### httpClientContextHandler

@Nullable private HttpClientContextHandler httpClientContextHandler
Optional handler to pre- and post-process context.

## Constructor Details

### HTTPResource

public HTTPResource(@Nonnull @ParameterName(name="client") org.apache.hc.client5.http.classic.HttpClient client, @Nonnull @NotEmpty @ParameterName(name="url") String url) throws IOException
Constructor.

Parameters:
  `client` - the client we use to connect with.
  `url` - URL to the remote data
Throws:
  `IOException` - if the URL was badly formed

### HTTPResource

public HTTPResource(@Nonnull @ParameterName(name="") org.apache.hc.client5.http.classic.HttpClient client, @Nonnull @ParameterName(name="url") URL url) throws IOException
Constructor.

Parameters:
  `client` - the client we use to connect with.
  `url` - URL to the remote data
Throws:
  `IOException` - if the URL was badly formed

## Method Details

### setHttpClientContextHandler

public void setHttpClientContextHandler(@Nonnull HttpClientContextHandler handler)
Set a handler to manipulate the `HttpClientContext`.

Parameters:
  `handler` - the handler to install
Since:
  5.4.0

### buildHttpClientContext

@Nonnull protected org.apache.hc.client5.http.cache.HttpCacheContext buildHttpClientContext()
Build the `HttpCacheContext` instance which will be used to invoke the `HttpClient` request.

Returns:
  a new instance of `HttpCacheContext`

### reportCachingStatus

protected void reportCachingStatus(@Nonnull org.apache.hc.client5.http.cache.HttpCacheContext context)
Print out to the log whether we hit the apache cache or not. http://hc.apache.org/httpcomponents-client-ga/tutorial/html/caching.html

Parameters:
  `context` - the context of the request

### getInputStream

@Nonnull public InputStream getInputStream() throws IOException
Return an `InputStream`.

It is expected that each call creates a fresh stream.

This requirement is particularly important when you consider an API such as JavaMail, which needs to be able to read the stream multiple times when creating mail attachments. For such a use case, it is required that each `getInputStream()` call returns a fresh stream.

Specified by:
  `getInputStream` in interface `InputStreamSource`
Specified by:
  `getInputStream` in interface `Resource`
Returns:
  the input stream for the underlying resource (must not be `null`)
Throws:
  `IOException` - if the stream could not be opened

### afterPropertiesSet

public void afterPropertiesSet() throws Exception

Specified by:
  `afterPropertiesSet` in interface `InitializingBean`
Throws:
  `Exception`

### setBeanName

public void setBeanName(@Nonnull String name)

Specified by:
  `setBeanName` in interface `BeanNameAware`

### exists

public boolean exists()
Return whether this resource actually exists in physical form.

This method performs a definitive existence check, whereas the existence of a `Resource` handle only guarantees a valid descriptor handle.

Specified by:
  `exists` in interface `Resource`
Specified by:
  `exists` in interface `Resource`
Returns:
  whether this resource actually exists in physical form.

### isFile

public boolean isFile()
Determine whether this resource represents a file in a file system.

A value of `true` strongly suggests (but does not guarantee) that a `Resource.getFile()` call will succeed.

This is conservatively `false` by default.

Specified by:
  `isFile` in interface `Resource`
Specified by:
  `isFile` in interface `Resource`
Returns:
  true iff this resource represents a file in a file system

### isReadable

public boolean isReadable()
Return whether the contents of this resource can be read, e.g. via `Resource.getInputStream()` or `Resource.getFile()`.

Will be `true` for typical resource descriptors; note that actual content reading may still fail when attempted. However, a value of `false` is a definitive indication that the resource content cannot be read.

Specified by:
  `isReadable` in interface `Resource`
Specified by:
  `isReadable` in interface `Resource`
Returns:
  whether the contents of this resource can be read.
See Also:
  - `Resource.getInputStream()`

### isOpen

public boolean isOpen()
Return whether this resource represents a handle with an open stream. If true, the InputStream cannot be read multiple times, and must be read and closed to avoid resource leaks.

Will be `false` for typical resource descriptors.

Specified by:
  `isOpen` in interface `Resource`
Specified by:
  `isOpen` in interface `Resource`
Returns:
  whether this resource represents a handle with an open stream.

### getURL

@Nonnull public URL getURL() throws IOException
Return a URL handle for this resource.

Specified by:
  `getURL` in interface `Resource`
Specified by:
  `getURL` in interface `Resource`
Returns:
  a URL handle for this resource.
Throws:
  `IOException` - if the resource cannot be resolved as URL, i.e. if the resource is not available as descriptor

### getURI

@Nonnull public URI getURI() throws IOException
Return a URI handle for this resource.

Specified by:
  `getURI` in interface `Resource`
Specified by:
  `getURI` in interface `Resource`
Returns:
  a URI handle for this resource.
Throws:
  `IOException` - if the resource cannot be resolved as URI, i.e. if the resource is not available as descriptor

### getFile

@Nonnull public File getFile() throws IOException
Return a File handle for this resource. Based on `UrlResource`.

Specified by:
  `getFile` in interface `Resource`
Specified by:
  `getFile` in interface `Resource`
Returns:
  a File handle for this resource.
Throws:
  `IOException` - if the resource cannot be resolved as absolute file path, i.e. if the resource is not available in a file system

### getResourceHeaders

@Nonnull protected org.apache.hc.core5.http.HttpResponse getResourceHeaders() throws IOException
Attempts to fetch only the headers for a given resource. If HEAD requests are unsupported then a more costly GET request is performed. NOTE This method returns a closed `ClassicHttpResponse`. See JSSH-25. It turns out that for the cases we need it this is OK and all three of them have regression tests. If they fail, this will be revisisted.

Returns:
  the response from the request
Throws:
  `IOException` - thrown if there is a problem contacting the resource

### getResponseHeader

@Nullable protected String getResponseHeader(String what) throws IOException
Send a Head to the client and interrogate the response for a particular response header.

Parameters:
  `what` - the repsonse header to look at
Returns:
  the value of that response, or null if things failed
Throws:
  `IOException` - from lower levels.

### contentLength

public long contentLength() throws IOException
Determine the content length for this resource.

Specified by:
  `contentLength` in interface `Resource`
Specified by:
  `contentLength` in interface `Resource`
Returns:
  the content length for this resource.
Throws:
  `IOException` - if the resource cannot be resolved (in the file system or as some other known physical resource type)

### lastModified

public long lastModified() throws IOException
Determine the last-modified timestamp for this resource.

Specified by:
  `lastModified` in interface `Resource`
Specified by:
  `lastModified` in interface `Resource`
Returns:
  the last-modified timestamp for this resource.
Throws:
  `IOException` - if the resource cannot be resolved (in the file system or as some other known physical resource type)

### createRelative

@Nonnull public HTTPResource createRelative(@Nonnull String relativePath) throws IOException
Based on `UrlResource`.

Specified by:
  `createRelative` in interface `Resource`
Throws:
  `IOException`

### createRelative

@Nonnull public HTTPResource createRelative(@Nonnull String relativePath, @Nullable HttpClientContextHandler handler) throws IOException
Create a resource relative to us, but use the supplied handler.

Parameters:
  `relativePath` - The path to create
  `handler` - (optional) the handler
Returns:
  the resource
Throws:
  `IOException` - if we cannot set things up correctly
Since:
  9.0.0

### createRelativeResource

@Nonnull public Resource createRelativeResource(@Nonnull String relativePath) throws IOException
Create a resource relative to this resource.

Specified by:
  `createRelativeResource` in interface `Resource`
Parameters:
  `relativePath` - the relative path (relative to this resource)
Returns:
  the resource handle for the relative resource
Throws:
  `IOException` - if the relative resource cannot be determined

### getFilename

@Nullable public String getFilename()
Determine a filename for this resource, i.e. typically the last part of the path: for example, "myfile.txt". This implementation returns the name of the file that this URL refers to.

Specified by:
  `getFilename` in interface `Resource`
Specified by:
  `getFilename` in interface `Resource`
Returns:
  `null` if this type of resource does not have a filename, otherwise the file name.
See Also:
  - `URL.getFile()`
  - `File.getName()`

### getDescription

@Nonnull public String getDescription()
Return a description for this resource, to be used for error output when working with the resource.

Implementations are also encouraged to return this value from their `toString` method.

Specified by:
  `getDescription` in interface `Resource`
Specified by:
  `getDescription` in interface `Resource`
Returns:
  a description for this resource.
See Also:
  - `Object.toString()`

### closeResponse

protected void closeResponse(@Nullable org.apache.hc.core5.http.ClassicHttpResponse response)
Close the HTTP response.

Parameters:
  `response` - the HTTP response