Initialisation
The main basis of this package is the
FlutterMapTileCaching object. There are other high level objects, but they are usually for more advanced usage, and can be explored in more detail through the API documentation.FMTC is a shorthand type alias for FlutterMapTileCaching, and works in exactly the same way. Often, documentation will use the shortened version to save space, and you should do so in your code as well.This singleton must first be initialised, usually in the
main (asynchronous) function at the start of your app.
main.dart
import 'package:flutter/widgets.dart';
import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await FlutterMapTileCaching.initialise();
// FMTC.instance;
// Run your app and do all of that other stuff
}
Once initialised, it is safe to use
FMTC.instance. At this point, most functionality is accessed through chaining, as described in Using Roots & Stores.You must call
initialise() before trying to use instance.Failure to do so will throw a StateError.In summary, in the extremely unlikely event of database corruption, FMTC can recover automatically (in most circumstances), with minimal data loss, given enough fatal app crashes - corruption cannot be caught in any other way.
Whilst it is (almost) impossible for one of the underlying Isar databases to become corrupted during normal usage, or even due to a bug, it can happen if the database file is modified manually.
In this case, it is currently impossible to avoid a fatal crash during initialisation, as the database reader/parser crashes all Dart threads & isolates without warning. Please see this issue I opened:
However, FMTC has a workaround.
By using a basic temporary text file, the IDs/filenames of successfully opened databases can be recorded. Once all databases have been opened, the file is deleted, meaning that the safety system will not intervene on the next app launch. However, if a database open attempt crashes the app, the file will not be deleted, and it will contain the list of safe databases.
Because the order in which databases are opened is determinate (alphabetical), the app can open every database one by one, (metaphorically) crossing it off the list. When there are no more safe databases, but more database files, the next database is deleted instead of being opened. The initialisation then continues as normal, still using the file appropriatley.
Therefore, one fatal crash is enough to detect one faulty database, and delete it, allowing the app to initialise normally on the next launch.
If there are multiple corrupted databases (
n), one fatal crash is needed per database, so the app will successfully open after n + 1.All of this means that FMTC can usually recover from a database corruption with minimal data loss. However, if the database filenames/IDs are also changed, the behaviour is unspecified, especially if the initialisation file already exists.
Last modified 1mo ago