Projects:File Management API/Specs
 | Back to Projects:File_Management_API |
Contents |
Goal
The main objective of this project is to provide an API that should be used as an standard for every process inside Openbravo that needs to create or handle files.
Functional Requirements
Current State
Currently there is not an standard way to handle the storage of files in Openbravo. Besides, it does not exist any configuration that allows to define how the storage should be done, with the except of attachments whose storage method can be defined using the Attachment Configuration window.
File Types
It has been identified four types of files:
- Permanent: files that are desired to be kept in the system in long-term.
- Temporary: files that are used just in the scope of a request. They are typically deleted once the request finishes.
- Shared Temporary: temporary files that can be accessed by different requests. This kind of files are currently used when printing some reports that are generated on a first request and later downloaded using a second one.
- Attachments: files kept in the system as attachments.
Storage Configuration
In order to allow users to define how the storage configuration of the different file types should be done, the Storage Configuration window will be created.
The existing Attachment Configuration window fits well with the desired way for configuring the storage methods, therefore it is going to be renamed as Storage Configuration and a new field called Storage Type it is also being added. The default value for this field will be Attachment because is the only file type that was possible to configure so far. With this change we are avoiding to have multiple ways of configuring file storage mechanisms. Note that the name of the table related to that window is not going to be changed to avoid a disruptive API change.
In the same way the Attachment Method table will be renamed as Storage Method.
Known Limitations
- Unlike the attachment configuration, if an storage configuration for a particular type of file (except for Attachment) has been used, and later it is replaced with another one, the files generated with the former configuration may be lost using the new one. This means that it would require to migrate the files from the old configuration to the new one before changing the storage configuration.
- The Metadata defined for the storage methods only apply for attachments.
Technical Specs
API Features
The file management API should provide the following features:
- Security: it will ensure that all files must be placed under an expected base path. It will prevent to perform path traversals when creating a file.
- Common API: it will unify the way of handling files avoiding duplicated and/or obsolete code.
- Cluster: support file management being in cluster mode.
Temporary Storage
The temporary files are a special kind of file type. This is because we always want to generate and work with them in the local file system. For this reason a new class called TemporaryStorage will be created. It will keep all the methods required to deal with temporary files.
Storage Handler
The new StorageHandler interface will provide the different actions involved in file handling:
- Create: create a new file. It will be possible to create files with any content or empty.
- Move: move a file from one location to another.
- Get: retrieve the file contents.
- toPath: creates a Path in the local file system that references a file in particular. This would be useful for cases that need to work with a file that is not stored in the local file system but in an external one (like Amazon S3 or Azure).
- Delete: deletes a file.
The classes implementing this interface will be annotated in order to link them with the Storage Configuration records created in the application.
Storage Type Management
The four type of files will be handled with different components that form the API:
- Permanent: handled with Storage Handler implementations. A default implementation that uses the local file system will be provided.
- Temporary: handled with the Temporary Storage API.
- Shared Temporary: handled with Storage Handler implementations. A default implementation that uses the local file system will be provided.
- Attachments: they will be continue handled with the existing AttachImplementationManager.