FileManagerModule

The FileManagerModule provides an abstraction layer for storing and retrieving files in an efficient way. Files are uniquely identified using a FileDescriptor and stored in a named FileRepository. Clients access all files and repositories through the central FileManager bean.

By default the FileManagerModule sets up local directory based file repositories and requires very little configuration.

1. Default configuration

The default configuration of the FileManagerModule will automatically create file based repositories in a single root folder (controller by the fileManagerModule.localRepositoriesRoot property). A new repository will be created when it is accessed for the first time. If no explicit repository id is specified for file access, default will be used.

2. Core classes

2.1. FileDescriptor

Files are identified by a unique FileDescriptor that determines in which backing FileRepository a file should be saved or from which it should be retrieved. A FileDescriptor has a URI property that is a globally unique String version of the descriptor. Any FileDescriptor can be serialized to and from its URI.

2.2. FileRepository

A FileRepository is identified by a unique repository id. The first part of a FileDescriptor will always contain the repository id. How a FileRepository stores its files is implementation dependent. This could be disk-based storage, database backed or any form of cloud storage. The purpose of the FileManager, FileDescriptor and FileRepository interfaces is to provide a flexible way for modules to interact with files, without knowing how or where they are actually persisted.

2.3. FileManager

The FileManager service bean (exposed) is the facade to access any FileRepository. It is the central interface that clients should use for accessing files. Using it is pretty straightforward, the interface methods are well-documented and fairly self-explanatory.

Example storing a file

// Create a new temporary file
File tempFile = fileManager.createTempFile();
// Write data to the temporary file
writeUploadedImage( tempFile );
// Move the file into the 'images' repository (this deletes the temp file)
FileDescriptor fd = fileManager.moveInto( "images", tempFile );
// Store the unique file descriptor in database
imageRecord.setFileUri( fd.getUri() );

Because a FileRepository can have different types of implementations, modify operations on java.io.File instances might be limited. To ensure maximum compatibility intermediate stages (using temporary files) or the InputSteam/OutputStream based methods should be used. See the FileRepository javadoc for more details.

3. Registering a FileRepository

Registering your own FileRepository can be done through the (exposed) FileRepositoryRegistry bean.

The default implementation will wrap all repositories in a FileRepositoryDelegate. Consumers can request a hard reference to a specific FileRepository using the FileManager#getRepository() methods. Because they actually get a FileRepositoryDelegate reference, the actual implementation can be modified at runtime through the repository registry.