FileResource

What is a FileResource?

A FileResource represents a single file being stored in the system. It always corresponds to a unique FileDescriptor and is handed out (managed) by a FileRepository.

FileResource is the equivalent of a Java File handle in the FileManagerModule virtual file system.

Example retrieving a file resource

FileResource fileResource = fileManager.getFileResource( fileDescriptor );

The generic FileResource is the interface that applications should use. You should avoid using specific implementations directly.

Checking existence

A file resource object is only a valid handle to file data. It does not mean that there is actual physical data available. Checking if physical data exists is done with exists().

fileResource.exists()

Creating file resources

A FileResource can always be retrieved as long as the FileDescriptor used is valid. Physical data is only added when data is written to the file resource.

The FileRepository provides some useful methods for automatically generating unique file resources which can be used for writing.

Creating a random unique FileResource for writing

FileResource file = fileRepository.createFileResource();

Upload an existing File to a new resource and delete the original when done

FileResource fileResource = fileRepository.createFileResource( file, true );

Generating a random unique FileDescriptor for a new FileResource

FileDescriptor descriptor = fileRepository.generateFileDescriptor();
FileResource file = fileRepository.getFileResource( descriptor );

Creating a new FileResource but specifying file extension

FileDescriptor descriptor = fileRepository.generateFileDescriptor().withExtensionFrom( file );
FileResource fileResource = fileRepository.getFileResource( descriptor );
fileResource.copyFrom( file, true ); // upload original file data and delete original when done

Copying the original file extension can be useful for mime type detection when uploading files.

Reading file data

You can access the data of a file by accessing the InputStream.

Accessing the InputStream when a file does not exist will usually result in an exception being thrown.

Example reading the InputStream

try (InputStream is = fileResource.getInputStream()) {
    String text = readStreamToString( is );
}

Copying file data

The FileResource interface additionally provides some copyTo() methods for copying the file data to another target. Use these methods when possible as they might have storage specific implementations which could result in improved performance.

Example copying file data to an output stream

try (OutputStream outputStream = createSomeOutputStream()) {
    fileResource.copyTo( outputStream );
}

Copying file data to an actual File

Sometimes you just need access to the file data as an actual File instance. You can do this using copyTo(File).

Example copying file data to a temporary file

File tempFile = fileManager.createTempFile();
fileResource.copyTo( tempFile );

Even though FileResource has a method getFile(), it should not be used. It is inherited from the generic Spring Resource interface but not implemented to avoid misuse when writing data.

FileResource.getFile() should always throw an UnsupportedOperationException.

Writing file data

Writing data to a FileResource is done by accessing the OutputStream. Writing to the OutputStream will either create or replace the physical data.

Example writing to the OutputStream

try (OutputStream os = fileResource.getOutputStream()) {
    writeDataToOutputStream( data, os );
}

Copying file data from another source

FileResource also provides some direct methods to copy the data from another source. Use these when possible as they might yield better overall performance.

Example copying data from a physical file

File uploadedFile;
fileResource.copyFrom( uploadedFile, true ); (1)

1	This copies the data from uploadedFile into the file resource, attempting to delete the uploadedFile when done. Depending on the `FileResource` implementation this might do a physical file move instead of a copy.

Deleting file data

Deleting the actual file data is done by calling delete().

fileResource.delete()

This does not affect the actual FileResource object, but calls to exist() should return false after a successful delete.

Spring WritableResource

The FileResource interface extends Spring Frameworks' WritableResource. This means additional methods like getFilename(), contentLength() and lastModified() are available. It also implies you can use a FileResource anywhere you can use a Spring Resource.

« File repository File resource Folder resource »