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 Details

    • 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:

    • 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: