initialise static method

Future<FlutterMapTileCaching> initialise({String? rootDirectory, FMTCSettings? settings, void errorHandler(FMTCInitialisationException error)?, bool disableInitialisationSafety = false, bool debugMode = false})

Initialise and prepare FMTC, by creating all neccessary directories/files and configuring the FlutterMapTileCaching singleton

Prefer to leave rootDirectory as null, which will use getApplicationDocumentsDirectory(). Alternatively, pass a custom directory - it is recommended to not use a cache directory, as the OS can clear these without notice at any time.

You must construct using this before using FlutterMapTileCaching.instance, otherwise a StateError will be thrown.

The initialisation safety system ensures that a corrupted database cannot prevent the app from launching. However, one fatal crash is necessary for each corrupted database, as this allows each one to be individually located and deleted, due to limitations in dependencies. Note that any triggering of the safety system will also reset the recovery database, meaning recovery information will be lost.

errorHandler must not (re)throw an error, as this interferes with the initialisation safety system, and may result in unnecessary data loss.

Setting disableInitialisationSafety true will disable the initialisation safety system, and is not recommended, as this may leave the application unable to launch if any database becomes corrupted.

Setting debugMode true can be useful to diagnose issues, either within your application or FMTC itself. It enables the Isar inspector and causes extra console logging in important areas. Prefer to leave disabled to prevent console pollution and to maximise performance. Whether FMTC chooses to listen to this value is also dependent on kDebugMode - see FlutterMapTileCaching.debugMode for more information. Extra logging is currently limited.

This returns a configured FlutterMapTileCaching, the same object as FlutterMapTileCaching.instance. Note that FMTC is an alias for this object.

Implementation

static Future<FlutterMapTileCaching> initialise({
  String? rootDirectory,
  FMTCSettings? settings,
  void Function(FMTCInitialisationException error)? errorHandler,
  bool disableInitialisationSafety = false,
  bool debugMode = false,
}) async {
  final directory = await ((rootDirectory == null
              ? await getApplicationDocumentsDirectory()
              : Directory(rootDirectory)) >>
          'fmtc')
      .create(recursive: true);

  settings ??= FMTCSettings();

  if (!disableInitialisationSafety) {
    final initialisationSafetyFile =
        directory >>> '.initialisationSafety.tmp';
    final needsRescue = await initialisationSafetyFile.exists();

    await initialisationSafetyFile.create();
    final writeSink =
        initialisationSafetyFile.openWrite(mode: FileMode.writeOnlyAppend);

    await FMTCRegistry.initialise(
      directory: directory,
      databaseMaxSize: settings.databaseMaxSize,
      databaseCompactCondition: settings.databaseCompactCondition,
      errorHandler: errorHandler,
      initialisationSafetyWriteSink: writeSink,
      safeModeSuccessfulIDs:
          needsRescue ? await initialisationSafetyFile.readAsLines() : null,
      debugMode: debugMode && kDebugMode,
    );

    await writeSink.close();
    await initialisationSafetyFile.delete();
  } else {
    await FMTCRegistry.initialise(
      directory: directory,
      databaseMaxSize: settings.databaseMaxSize,
      databaseCompactCondition: settings.databaseCompactCondition,
      errorHandler: errorHandler,
      initialisationSafetyWriteSink: null,
      safeModeSuccessfulIDs: null,
      debugMode: debugMode && kDebugMode,
    );
  }

  return _instance = FMTC._(
    rootDirectory: RootDirectory._(directory),
    settings: settings,
    debugMode: debugMode,
  );
}