Files of the app
FileTemplate is a bean for the app's own files, in the right directory of every platform. It writes and reads text, bytes and objects (as JSON), in three places: support (private, kept, backed up), cache (the system may clear it) and documents (the user sees it). On the web every place is IndexedDB. It has no properties.
Why
Every app writes a few files: a catalog for offline use, cached covers, an export. Each time it needs path_provider, the right directory per platform, JSON code, and care for half-written files. The template does it once, like JdbcTemplate or RestTemplate in Spring: a template over a replaceable store.
Example
@Service()
class Library {
Library(this.files);
final FileTemplate files;
// An object as JSON, through the application's ObjectMapper.
Future<void> save(List<Book> books) => files.write('catalog.json', books);
Future<List<Book>> load() async =>
await files.read<List<Book>>(
'catalog.json',
const ListType<Book>(ClassType<Book>()),
) ??
[];
Future<void> cacheCover(String id, Uint8List png) =>
files.cache.write('covers/$id.png', png); // the OS may clear it
Future<void> export(String csv) =>
files.documents.write('books.csv', csv); // the user sees it
}
The methods
| Method | What it does |
|---|---|
write(path, value) |
Writes text (String), bytes (Uint8List) or an object (JSON through the application's ObjectMapper) |
read<T>(path, [type]) |
Reads it back; a missing file reads as null. readString and readBytes on a place |
exists(path) |
Whether the file exists |
delete(path) |
Deletes a file or a folder |
list(prefix) |
The paths below a folder when prefix ends in /, else the paths that start with it |
modifiedAt(path) |
When the file was last written |
On files itself they act on support; files.cache and files.documents (and files.support) are the other places, each a FileArea with the same methods.
The places
| Place | In code | What it is |
|---|---|---|
support |
files.write(...) |
The app's private data, kept and backed up; the default |
cache |
files.cache.write(...) |
The system may clear it |
documents |
files.documents.write(...) |
The user's documents folder |
The directories are the ones path_provider finds. On Windows support is %LOCALAPPDATA%\<company>\<product>, the machine's own, not the roaming directory, and cache is its cache folder. On the web all are IndexedDB.
Safe paths and writes
- Writes are atomic: a temporary file beside the target, then a rename. A crash never leaves half a file.
- A path stays inside its place:
..and absolute paths throw anArgumentError.
Temporary files
Temporary files have unique names in a folder of the run (<system temp>/spring/<run id>/):
// A file for the block only: deleted after it, also after an error.
final small = await files.temp(suffix: '.jpg', (file) async {
await file.writeAsBytes(photo); // or File(file.path) for a real file
return compress(File(file.path));
});
// A folder for the block only.
await files.tempDir((dir) => unzip(archive, into: dir.path));
// Yours to delete.
final keep = await files.createTemp();
What a block or createTemp leaves is removed when the context closes, and the folders of runs that died at the next start. On the web temporary files are in memory: they have no path, and tempDir is unsupported.
Replacing the store
Declare a FileStore bean (an encrypting one, a remote one) and FileTemplate, the theme cache and the theme-choice store follow. Declare a FileTemplate bean to replace the template itself. InMemoryFileStore keeps everything in memory, for tests.
// Tests write into memory, not the device.
final app = springBootTest(
springApplication,
overrides: [BeanOverride<FileStore>(InMemoryFileStore())],
);
What uses it
- A theme downloaded from a URL is cached in
support, inspring/themes/(see Theme properties). - Images of the theme from the network are cached in
spring/images/(see Images). - The theme the user chose is kept in
spring/theme-choice(see Themes).
In Spring (Java)
Spring has no such template; the shape (a template over a replaceable store) is the one of JdbcTemplate, and of SecretTemplate in the security starter.