アプリのファイル

FileTemplate は、すべてのプラットフォームの正しいディレクトリにあるアプリ自身のファイルのための Bean です。テキスト、バイト、オブジェクト (JSON として) を、三つの場所に読み書きします。support (プライベートで、保持され、バックアップされる)、cache (システムが消去することがある)、documents (ユーザーに見える) です。Web ではどの場所も IndexedDB です。プロパティはありません。

使う理由

どのアプリもいくつかのファイルを書きます。オフラインで使うためのカタログ、キャッシュした表紙、エクスポートなどです。そのたびに path_provider、プラットフォームごとの正しいディレクトリ、JSON のコード、書きかけのファイルへの配慮が必要です。テンプレートは、Spring の JdbcTemplate や RestTemplate のように、置き換え可能なストアの上のテンプレートとして、これを一度だけ行います。

例

@Service()
class Library {
  Library(this.files);

  final FileTemplate files;

  // アプリケーションの ObjectMapper を通じた、JSON としてのオブジェクト。
  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);   // OS が消去することがある

  Future<void> export(String csv) =>
      files.documents.write('books.csv', csv);    // ユーザーに見える
}

メソッド

メソッド 働き
write(path, value) テキスト (String)、バイト (Uint8List)、またはオブジェクト (アプリケーションの ObjectMapper を通じた JSON) を書く
read<T>(path, [type]) それを読み戻す。存在しないファイルは null として読まれる。場所には readString と readBytes がある
exists(path) ファイルが存在するかどうか
delete(path) ファイルまたはフォルダーを削除する
list(prefix) prefix が / で終わる場合はフォルダーの下のパス、それ以外はそれで始まるパス
modifiedAt(path) ファイルが最後に書かれた時刻

files 自体のメソッドは support に作用します。files.cache と files.documents (そして files.support) が他の場所で、それぞれ同じメソッドを持つ FileArea です。

場所

場所 コードでは 内容
support files.write(...) アプリのプライベートなデータ。保持され、バックアップされる。デフォルト
cache files.cache.write(...) システムが消去することがある
documents files.documents.write(...) ユーザーの書類フォルダー

ディレクトリは path_provider が見つけるものです。Windows では support は %LOCALAPPDATA%\<company>\<product> で、ローミングのディレクトリではなくマシン自身のものです。cache はその cache フォルダーです。Web ではすべてが IndexedDB です。

安全なパスと書き込み

一時ファイル

一時ファイルは、実行ごとのフォルダー (<system temp>/spring/<run id>/) の中で一意の名前を持ちます。

// ブロックのためだけのファイル: その後、エラーの後でも削除される。
final small = await files.temp(suffix: '.jpg', (file) async {
  await file.writeAsBytes(photo);          // または実際のファイルとして File(file.path)
  return compress(File(file.path));
});

// ブロックのためだけのフォルダー。
await files.tempDir((dir) => unzip(archive, into: dir.path));

// 自分で削除するもの。
final keep = await files.createTemp();

ブロックや createTemp が残したものはコンテキストが閉じるときに取り除かれ、異常終了した実行のフォルダーは次の起動時に取り除かれます。Web では一時ファイルはメモリ上にあり、path を持たず、tempDir はサポートされません。

ストアを置き換える

FileStore Bean (暗号化するもの、リモートのもの) を宣言すると、FileTemplate、テーマのキャッシュ、テーマの選択のストアがそれに従います。テンプレート自体を置き換えるには、FileTemplate Bean を宣言します。InMemoryFileStore は、テストのためにすべてをメモリに保持します。

// テストはデバイスではなくメモリに書く。
final app = springBootTest(
  springApplication,
  overrides: [BeanOverride<FileStore>(InMemoryFileStore())],
);

これを使うもの

Spring (Java) との対応

Spring にはこうしたテンプレートはありません。形 (置き換え可能なストアの上のテンプレート) は JdbcTemplate や、セキュリティスターターの SecretTemplate のものです。

関連項目