org.springframework.core.io

## Class FileSystemResource

- java.lang.Object
- - org.springframework.core.io.AbstractResource
  - - org.springframework.core.io.FileSystemResource

- All Implemented Interfaces:
    InputStreamSource, Resource, WritableResource

      public class FileSystemResource
      extends AbstractResource
      implements WritableResource

  `Resource` implementation for `java.io.File` and `java.nio.file.Path` handles with a file system target. Supports resolution as a `File` and also as a `URL`. Implements the extended `WritableResource` interface.

  Note: As of Spring Framework 5.0, this `Resource` implementation uses NIO.2 API for read/write interactions. As of 5.1, it may be constructed with a `Path` handle in which case it will perform all file system interactions via NIO.2, only resorting to `File` on `getFile()`.

  Since:
    28.12.2003
  Author:
    Juergen Hoeller
  See Also:
    `FileSystemResource(String)`, `FileSystemResource(File)`, `FileSystemResource(Path)`, `File`, `Files`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FileSystemResource(File file)` Create a new `FileSystemResource` from a `File` handle.
    `FileSystemResource(FileSystem fileSystem, String path)` Create a new `FileSystemResource` from a `FileSystem` handle, locating the specified path.
    `FileSystemResource(Path filePath)` Create a new `FileSystemResource` from a `Path` handle, performing all file system interactions via NIO.2 instead of `File`.
    `FileSystemResource(String path)` Create a new `FileSystemResource` from a file path.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `contentLength()` This implementation returns the underlying File/Path length.
    `Resource` | `createRelative(String relativePath)` This implementation creates a FileSystemResource, applying the given path relative to the path of the underlying file of this resource descriptor.
    `boolean` | `equals(Object other)` This implementation compares the underlying file paths.
    `boolean` | `exists()` This implementation returns whether the underlying file exists.
    `String` | `getDescription()` This implementation returns a description that includes the absolute path of the file.
    `File` | `getFile()` This implementation returns the underlying File reference.
    `String` | `getFilename()` This implementation returns the name of the file.
    `InputStream` | `getInputStream()` This implementation opens an NIO file stream for the underlying file.
    `OutputStream` | `getOutputStream()` This implementation opens a FileOutputStream for the underlying file.
    `String` | `getPath()` Return the file path for this resource.
    `URI` | `getURI()` This implementation returns a URI for the underlying file.
    `URL` | `getURL()` This implementation returns a URL for the underlying file.
    `int` | `hashCode()` This implementation returns the hash code of the underlying file path.
    `boolean` | `isFile()` This implementation always indicates a file.
    `boolean` | `isReadable()` This implementation checks whether the underlying file is marked as readable (and corresponds to an actual file with content, not to a directory).
    `boolean` | `isWritable()` This implementation checks whether the underlying file is marked as writable (and corresponds to an actual file with content, not to a directory).
    `long` | `lastModified()` This implementation returns the underlying File/Path last-modified time.
    `ReadableByteChannel` | `readableChannel()` This implementation opens a FileChannel for the underlying file.
    `WritableByteChannel` | `writableChannel()` This implementation opens a FileChannel for the underlying file.

    - ### Methods inherited from class org.springframework.core.io.AbstractResource

      `getFileForLastModifiedCheck, isOpen, toString`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

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

      `isOpen`

- - ### Constructor Detail

    - #### FileSystemResource

          public FileSystemResource(String path)

      Create a new `FileSystemResource` from a file path.

      Note: When building relative resources via `createRelative(java.lang.String)`, it makes a difference whether the specified resource base path here ends with a slash or not. In the case of "C:/dir1/", relative paths will be built underneath that root: e.g. relative path "dir2" → "C:/dir1/dir2". In the case of "C:/dir1", relative paths will apply at the same directory level: relative path "dir2" → "C:/dir2".

      Parameters:
        `path` - a file path
      See Also:
        `FileSystemResource(Path)`

    - #### FileSystemResource

          public FileSystemResource(File file)

      Create a new `FileSystemResource` from a `File` handle.

      Note: When building relative resources via `createRelative(java.lang.String)`, the relative path will apply at the same directory level: e.g. new File("C:/dir1"), relative path "dir2" → "C:/dir2"! If you prefer to have relative paths built underneath the given root directory, use the `constructor with a file path` to append a trailing slash to the root path: "C:/dir1/", which indicates this directory as root for all relative paths.

      Parameters:
        `file` - a File handle
      See Also:
        `FileSystemResource(Path)`, `getFile()`

    - #### FileSystemResource

          public FileSystemResource(Path filePath)

      Create a new `FileSystemResource` from a `Path` handle, performing all file system interactions via NIO.2 instead of `File`.

      In contrast to `PathResource`, this variant strictly follows the general `FileSystemResource` conventions, in particular in terms of path cleaning and `createRelative(String)` handling.

      Note: When building relative resources via `createRelative(java.lang.String)`, the relative path will apply at the same directory level: e.g. Paths.get("C:/dir1"), relative path "dir2" → "C:/dir2"! If you prefer to have relative paths built underneath the given root directory, use the `constructor with a file path` to append a trailing slash to the root path: "C:/dir1/", which indicates this directory as root for all relative paths. Alternatively, consider using `PathResource(Path)` for `java.nio.path.Path` resolution in `createRelative`, always nesting relative paths.

      Parameters:
        `filePath` - a Path handle to a file
      Since:
        5.1
      See Also:
        `FileSystemResource(File)`

    - #### FileSystemResource

          public FileSystemResource(FileSystem fileSystem,
                                    String path)

      Create a new `FileSystemResource` from a `FileSystem` handle, locating the specified path.

      This is an alternative to `FileSystemResource(String)`, performing all file system interactions via NIO.2 instead of `File`.

      Parameters:
        `fileSystem` - the FileSystem to locate the path within
        `path` - a file path
      Since:
        5.1.1
      See Also:
        `FileSystemResource(File)`

  - ### Method Detail

    - #### getPath

          public final String getPath()

      Return the file path for this resource.

    - #### exists

          public boolean exists()

      This implementation returns whether the underlying file exists.
      Specified by:
        `exists` in interface `Resource`
      Overrides:
        `exists` in class `AbstractResource`
      See Also:
        `File.exists()`, `Files.exists(Path, java.nio.file.LinkOption...)`

    - #### isReadable

          public boolean isReadable()

      This implementation checks whether the underlying file is marked as readable (and corresponds to an actual file with content, not to a directory).
      Specified by:
        `isReadable` in interface `Resource`
      Overrides:
        `isReadable` in class `AbstractResource`
      See Also:
        `File.canRead()`, `File.isDirectory()`, `Files.isReadable(Path)`, `Files.isDirectory(Path, java.nio.file.LinkOption...)`

    - #### getInputStream

          public InputStream getInputStream()
                                     throws IOException

      This implementation opens an NIO file stream for the underlying file.
      Specified by:
        `getInputStream` in interface `InputStreamSource`
      Returns:
        the input stream for the underlying resource (must not be `null`)
      Throws:
        `FileNotFoundException` - if the underlying resource does not exist
        `IOException` - if the content stream could not be opened
      See Also:
        `Files.newInputStream(Path, java.nio.file.OpenOption...)`

    - #### isWritable

          public boolean isWritable()

      This implementation checks whether the underlying file is marked as writable (and corresponds to an actual file with content, not to a directory).
      Specified by:
        `isWritable` in interface `WritableResource`
      See Also:
        `File.canWrite()`, `File.isDirectory()`, `Files.isWritable(Path)`, `Files.isDirectory(Path, java.nio.file.LinkOption...)`

    - #### getOutputStream

          public OutputStream getOutputStream()
                                       throws IOException

      This implementation opens a FileOutputStream for the underlying file.
      Specified by:
        `getOutputStream` in interface `WritableResource`
      Throws:
        `IOException` - if the stream could not be opened
      See Also:
        `Files.newOutputStream(Path, java.nio.file.OpenOption...)`

    - #### getURL

          public URL getURL()
                     throws IOException

      This implementation returns a URL for the underlying file.
      Specified by:
        `getURL` in interface `Resource`
      Overrides:
        `getURL` in class `AbstractResource`
      Throws:
        `IOException` - if the resource cannot be resolved as URL, i.e. if the resource is not available as a descriptor
      See Also:
        `File.toURI()`, `Path.toUri()`

    - #### getURI

          public URI getURI()
                     throws IOException

      This implementation returns a URI for the underlying file.
      Specified by:
        `getURI` in interface `Resource`
      Overrides:
        `getURI` in class `AbstractResource`
      Throws:
        `IOException` - if the resource cannot be resolved as URI, i.e. if the resource is not available as a descriptor
      See Also:
        `File.toURI()`, `Path.toUri()`

    - #### isFile

          public boolean isFile()

      This implementation always indicates a file.
      Specified by:
        `isFile` in interface `Resource`
      Overrides:
        `isFile` in class `AbstractResource`
      See Also:
        `Resource.getFile()`

    - #### getFile

          public File getFile()

      This implementation returns the underlying File reference.
      Specified by:
        `getFile` in interface `Resource`
      Overrides:
        `getFile` in class `AbstractResource`
      See Also:
        `InputStreamSource.getInputStream()`

    - #### readableChannel

          public ReadableByteChannel readableChannel()
                                              throws IOException

      This implementation opens a FileChannel for the underlying file.
      Specified by:
        `readableChannel` in interface `Resource`
      Overrides:
        `readableChannel` in class `AbstractResource`
      Returns:
        the byte channel for the underlying resource (must not be `null`)
      Throws:
        `FileNotFoundException` - if the underlying resource doesn't exist
        `IOException` - if the content channel could not be opened
      See Also:
        `FileChannel`

    - #### writableChannel

          public WritableByteChannel writableChannel()
                                              throws IOException

      This implementation opens a FileChannel for the underlying file.
      Specified by:
        `writableChannel` in interface `WritableResource`
      Returns:
        the byte channel for the underlying resource (must not be `null`)
      Throws:
        `FileNotFoundException` - if the underlying resource doesn't exist
        `IOException` - if the content channel could not be opened
      See Also:
        `FileChannel`

    - #### contentLength

          public long contentLength()
                             throws IOException

      This implementation returns the underlying File/Path length.
      Specified by:
        `contentLength` in interface `Resource`
      Overrides:
        `contentLength` in class `AbstractResource`
      Throws:
        `IOException` - if the resource cannot be resolved (in the file system or as some other known physical resource type)
      See Also:
        `InputStreamSource.getInputStream()`

    - #### lastModified

          public long lastModified()
                            throws IOException

      This implementation returns the underlying File/Path last-modified time.
      Specified by:
        `lastModified` in interface `Resource`
      Overrides:
        `lastModified` in class `AbstractResource`
      Throws:
        `IOException` - if the resource cannot be resolved (in the file system or as some other known physical resource type)
      See Also:
        `AbstractResource.getFileForLastModifiedCheck()`

    - #### createRelative

          public Resource createRelative(String relativePath)

      This implementation creates a FileSystemResource, applying the given path relative to the path of the underlying file of this resource descriptor.
      Specified by:
        `createRelative` in interface `Resource`
      Overrides:
        `createRelative` in class `AbstractResource`
      Parameters:
        `relativePath` - the relative path (relative to this resource)
      Returns:
        the resource handle for the relative resource
      See Also:
        `StringUtils.applyRelativePath(String, String)`

    - #### getFilename

          public String getFilename()

      This implementation returns the name of the file.
      Specified by:
        `getFilename` in interface `Resource`
      Overrides:
        `getFilename` in class `AbstractResource`
      See Also:
        `File.getName()`, `Path.getFileName()`

    - #### getDescription

          public String getDescription()

      This implementation returns a description that includes the absolute path of the file.
      Specified by:
        `getDescription` in interface `Resource`
      See Also:
        `File.getAbsolutePath()`, `Path.toAbsolutePath()`

    - #### equals

          public boolean equals(@Nullable
                                Object other)

      This implementation compares the underlying file paths.
      Overrides:
        `equals` in class `AbstractResource`
      See Also:
        `Resource.getDescription()`

    - #### hashCode

          public int hashCode()

      This implementation returns the hash code of the underlying file path.
      Overrides:
        `hashCode` in class `AbstractResource`
      See Also:
        `Resource.getDescription()`