SQLiteDataManager

A data manager that stores Measurements as JSON in a local SQLite database.

Used when the protocol's data endpoint is a SQLiteDataEndPoint, which is the default for a SmartphoneStudyProtocol. Backends (e.g. carp_backend) read from this database and upload rows marked as not uploaded.

Key points:

• One database file is shared by all deployments in the app. Rows are keyed by deployment ID, device role name and the measurement's record ID.
• Duplicates (same deployment, device role name and record ID) are ignored.
• Inserts are batched: rows are buffered and written in one transaction every 500 ms. close writes any remaining rows.
• Write errors are logged and the batch is dropped.

Measurements are stored in the MEASUREMENT_TABLE_NAME table.

The path and filename format is ~/carp-data.db, where ~ is the folder where SQLite places its database files.

On iOS, this is the NSDocumentsDirectory and the files can be accessed via the MacOS Finder.

On Android, Flutter files are stored in the databases directory, which is located in the data/data/<package_name>/databases/ folder. Files can be accessed via AndroidStudio.

Inheritance

• Object
• AbstractDataManager
• SQLiteDataManager

Constructors

SQLiteDataManager

SQLiteDataManager()

Constants

DATABASE_NAME

String const DATABASE_NAME

Name of the database file, without the .db extension.

DATATYPE_COLUMN

String const DATATYPE_COLUMN

DEPLOYMENT_ID_COLUMN

String const DEPLOYMENT_ID_COLUMN

DEVICE_ROLE_NAME_COLUMN

String const DEVICE_ROLE_NAME_COLUMN

ID_COLUMN

String const ID_COLUMN

MEASUREMENT_COLUMN

String const MEASUREMENT_COLUMN

The JSON-encoded Measurement.

MEASUREMENT_TABLE_NAME

String const MEASUREMENT_TABLE_NAME

Name of the table holding the measurements.

RECORD_ID_COLUMN

String const RECORD_ID_COLUMN

The Data.recordId of the measurement, used to drop duplicates.

TRIGGER_ID_COLUMN

String const TRIGGER_ID_COLUMN

ID of the trigger that collected the measurement, or 0 if unknown.

UPLOADED_COLUMN

String const UPLOADED_COLUMN

Upload flag column: 0 when stored. An uploader that keeps rows after upload sets it to 1.

Properties

database

Database? database

getter/setter pair

The open database, or null until configure has been called.

databaseName

String get databaseName

Full path and name of the database.

type

1. @override

String get type

override

The type of this data manager as enumerated in DataEndPointTypes.

Methods

close

1. @override

Future<void> close()

override

Flushes any buffered data and closes this data manager.

After calling close the data manager can no longer be used.

configure

1. @override

Future<void> configure({

1. required DataEndPoint dataEndPoint,
2. required SmartphoneDeployment deployment,
3. required Stream<Measurement> measurements,

})

override

Configures the data manager with the study deployment, the dataEndPoint, and the stream of measurements to handle.

Call this before any data is handled.

onMeasurement

1. @override

Future<void> onMeasurement(

1. Measurement measurement

)

override

On each measurement collected, the onMeasurement handler is called.

Implementations of this interface should handle how to save or upload the measurement.