Module net.shibboleth.utilities.java.support

Package net.shibboleth.utilities.java.support.resource

Interface Resource

public interface Resource

An interface representing a data resource.

This is API-compatible with the Spring Resource but allows Resource-consuming code to not require Spring.

Shibboleth components only implement this interface if they also implement the Spring Resource interface. Refer to the Spring documentation to implement other versions of this in a Spring-free environment.

Method Summary

Modifier and Type	Method	Description
long	contentLength()	Determine the content length for this resource.
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.
URI	getURI()	Return a URI handle for this resource.
URL	getURL()	Return a URL handle for this resource.
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.

Method Detail

exists

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.

Returns:

whether this resource actually exists in physical form.

isReadable

boolean isReadable()

Return whether the contents of this resource can be read, e.g. via getInputStream() or 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.

Returns:

whether the contents of this resource can be read.

See Also:

getInputStream()

isOpen

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.

Returns:

whether this resource represents a handle with an open stream.

getURL

URL getURL()
    throws IOException

Return a URL handle for this 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

URI getURI()
    throws IOException

Return a URI handle for this 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

File getFile()
      throws IOException

Return a File handle for this 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

getInputStream

@Nonnull
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.

Returns:

the input stream for the underlying resource (must not be null)

Throws:

IOException - if the stream could not be opened

contentLength

long contentLength()
            throws IOException

Determine the content length for this 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

long lastModified()
           throws IOException

Determine the last-modified timestamp for this 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)

createRelativeResource

Resource createRelativeResource(String relativePath)
                         throws IOException

Create a resource relative to this 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

String getFilename()

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

Returns:

null if this type of resource does not have a filename, otherwise the file name.

getDescription

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.

Returns:

a description for this resource.

See Also:

Object.toString()