FileManager Module


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. The FileManagerModule provides several FileRepository implementations by default.


  • Has default FileRepository implementations for saving files locally or on an Amazon S3 Bucket

  • Provides an abstraction layer for file saving with a FileManager service

  • Provides a file upload control (if EntityModule is present) and an abstraction layer for persisting files using the FileReference entity.

  • Add metadata to a file using FileReferenceProperties.

Saving files

How files are saved are handled by the different FileRepository implementations. This module provides default implementations for local and Amazon S3 Bucket storage. It’s also possible to provide your own FileRepository.


The LocalFileRepository provides a way to store the files locally. This implementation provides a simple implementation that stores all files in a single root directory. More information can be found in the Supported file system section.

S3 bucket

The AwsS3FileRepository provides a way to store files on an Amazon S3 Bucket. More information can be found can be found in the Amazon S3 section.

Azure Blob Storage

The AzureFileRepository provides a way to store files on an Azure Blob Storage container. More information can be found can be found in the Azure Blob Storage section.

FTP/FTPS Storage

The SpringIntegrationFtpFileRepository provides a way to store files on a (remote) file system using FTP. More information can be found can be found in the FTP/FTPS section.


You can determine how your physical files are persisted by registering your own FileRepository. This can be done through the 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.

Add a custom FileRepository
public class CustomFileRepositoryConfiguration {
    public void registerS3Repository(FileRepositoryRegistry registry, FileManager fileManager) {
        registry.registerRepository(new LocalFileRepository("otherRepository", "local-data/rootFolder"));

Storing & uploading files

To handle file upload and persistence the FileReference entity can be used. The FileReference entity adds an abstraction layer for rendering a FileUploadFormElement. It also provides a link to the physically saved file.

Example of storing a file linked to an entity
public class Invoice extends SettableIdBasedEntity<Invoice> {
    private FileReference attachment;

You can find more information and implementation examples in the FileReference section.