Package net.shibboleth.shared.spring.resource

# Class ConditionalResource

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

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

public class ConditionalResource extends AbstractIdentifiedInitializableComponent implements Resource, BeanNameAware, Resource
A wrapper that guards a `Resource` that may be absent by returning an empty bean file instead.

Since:
  5.4.0

## Field Summary

Fields
Modifier and Type
Field
Description
`private static final String`
`DEFAULT_CONTENT`
Dummy content.
`private String`
`defaultContent`
Content to return if the resource is missing.
`private final org.slf4j.Logger`
`log`
Logger.
`private String`
`logPrefix`
Cached log prefix.
`private final Resource`
`wrappedResource`
Resource to wrap.

## Constructor Summary

Constructors
Constructor
Description
`ConditionalResource(Resource wrapped)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`long`
`contentLength()`
Determine the content length for this resource.
`Resource`
`createRelative(String relativePath)`
`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 String`
`getLogPrefix()`
Return a prefix for logging messages for this component.
`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.
`void`
`setBeanName(String name)`
`void`
`setDefaultContent(String content)`
Set the default content to return if the underlying resource is absent.
`void`
`setId(String id)`
Sets the ID of this component.

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

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

### 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

### DEFAULT_CONTENT

@Nonnull @NotEmpty private static final String DEFAULT_CONTENT
Dummy content.

See Also:
  - Constant Field Values

### log

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

### logPrefix

@Nullable private String logPrefix
Cached log prefix.

### wrappedResource

@Nonnull private final Resource wrappedResource
Resource to wrap.

### defaultContent

@NonnullAfterInit private String defaultContent
Content to return if the resource is missing.

## Constructor Details

### ConditionalResource

public ConditionalResource(@Nonnull Resource wrapped)
Constructor.

Parameters:
  `wrapped` - the resource to wrap

## Method Details

### setId

public void setId(@Nonnull @NotEmpty String id)
Sets the ID of this component. The component must not yet be initialized. NOTE - this declaration makes the method public

Overrides:
  `setId` in class `AbstractIdentifiedInitializableComponent`
Parameters:
  `id` - ID of the component

### setDefaultContent

public void setDefaultContent(@Nonnull String content)
Set the default content to return if the underlying resource is absent.

Parameters:
  `content` - default "empty" content
Since:
  6.1.0

### 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

### 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

### 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.

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

### 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 Resource createRelative(@Nonnull String relativePath) throws IOException

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

### getFilename

public String getFilename()
Determine a filename for this resource, i.e. typically the last part of the path: for example, "myfile.txt".

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.

### 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()`

### getLogPrefix

@Nonnull @NotEmpty protected String getLogPrefix()
Return a prefix for logging messages for this component.

Returns:
  a string for insertion at the beginning of any log messages