SQLiteDataManager class

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

Constructors

SQLiteDataManager()

Properties

database ↔ Database?
The open database, or null until configure has been called.
getter/setter pair
databaseName → String
Full path and name of the database.
no setter
dataEndPoint → DataEndPoint?
The DataEndPoint that this data manager is handling.
no setterinherited
deployment → SmartphoneDeployment
The deployment using this data manager.
no setterinherited
events → Stream<DataManagerEvent>
Stream of data manager events, see DataManagerEventTypes.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
studyDeploymentId → String
The ID of the study deployment that this manager is handling.
no setterinherited
type → String
The type of this data manager as enumerated in DataEndPointTypes.
no setteroverride

Methods

addEvent(DataManagerEvent event) → void
Adds event to the events stream.
inherited
close() → Future<void>
Flushes any buffered data and closes this data manager.
override
configure({required DataEndPoint dataEndPoint, required SmartphoneDeployment deployment, required Stream<Measurement> measurements}) → Future<void>
Configures the data manager with the study deployment, the dataEndPoint, and the stream of measurements to handle.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onDone() → Future<void>
When the data stream closes, the onDone handler is called. Default implementation is a no-op function. If another behavior is wanted, implementations of this abstract data manager should handle closing of the data stream.
inherited
onError(Object? error) → Future<void>
Saves error as an Error measurement via onMeasurement.
inherited
onMeasurement(Measurement measurement) → Future<void>
On each measurement collected, the onMeasurement handler is called.
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

DATABASE_NAME → const String
Name of the database file, without the .db extension.
DATATYPE_COLUMN → const String
DEPLOYMENT_ID_COLUMN → const String
DEVICE_ROLE_NAME_COLUMN → const String
ID_COLUMN → const String
MEASUREMENT_COLUMN → const String
The JSON-encoded Measurement.
MEASUREMENT_TABLE_NAME → const String
Name of the table holding the measurements.
RECORD_ID_COLUMN → const String
The Data.recordId of the measurement, used to drop duplicates.
TRIGGER_ID_COLUMN → const String
ID of the trigger that collected the measurement, or 0 if unknown.
UPLOADED_COLUMN → const String
Upload flag column: 0 when stored. An uploader that keeps rows after upload sets it to 1.