Package 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: This `Resource` implementation uses NIO.2 API for read/write interactions and 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, Sam Brannen
See Also:
  - `FileSystemResource(String)`
  - `FileSystemResource(File)`
  - `FileSystemResource(Path)`
  - `File`
  - `Files`

## Constructor Summary

Constructors
Constructor
Description
`FileSystemResource(File file)`
Create a new `FileSystemResource` from a `File` handle.
`FileSystemResource(String path)`
Create a new `FileSystemResource` from a file path.
`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`.

## Method Summary

Modifier and Type
Method
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.
`byte[]`
`getContentAsByteArray()`
Return the contents of this resource as a byte array.
`String`
`getContentAsString(Charset charset)`
Return the contents of this resource as a string, using the specified charset.
`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.
`final 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 Details

### 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: for example, 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: for example, 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: for example, 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 Details

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

### getContentAsByteArray

public byte[] getContentAsByteArray() throws IOException
Description copied from interface: `Resource`
Return the contents of this resource as a byte array.

Specified by:
  `getContentAsByteArray` in interface `Resource`
Returns:
  the contents of this resource as byte array
Throws:
  `FileNotFoundException` - if the resource cannot be resolved as absolute file path, i.e. if the resource is not available in a file system
  `IOException` - in case of general resolution/reading failures

### getContentAsString

public String getContentAsString(Charset charset) throws IOException
Description copied from interface: `Resource`
Return the contents of this resource as a string, using the specified charset.

Specified by:
  `getContentAsString` in interface `Resource`
Parameters:
  `charset` - the charset to use for decoding
Returns:
  the contents of this resource as a `String`
Throws:
  `FileNotFoundException` - if the resource cannot be resolved as absolute file path, i.e. if the resource is not available in a file system
  `IOException` - in case of general resolution/reading failures

### 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`
Returns:
  the content length (or -1 if undetermined)
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`
Returns:
  the last-modified timestamp (or 0 if not known)
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:
  - `getPath()`

### hashCode

public int hashCode()
This implementation returns the hash code of the underlying file path.

Overrides:
  `hashCode` in class `AbstractResource`
See Also:
  - `getPath()`