Skip to content
CARP Documentation

PersistenceService

Stores running studies and the user task queue in a local SQLite database, so they survive an app restart.

A singleton, accessed as PersistenceService(). Initialized by SmartPhoneClientManager.configure, which then restores studies and tasks. It stores:

After init, changes are saved automatically: it listens to SmartphoneClientRepository.studyStatusEvents and AppTaskController.userTaskEvents. Database errors are logged, not thrown.

This is separate from the measurement database used by SQLiteDataManager.

Studies are stored in the studies table and user tasks are stored in the task_queue table.

The path and filename format for the database is

~/carp.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.

Constructors

PersistenceService

PersistenceService()

Get the singleton persistence layer.

Constants

CREATED_ON_COLUMN

String const CREATED_ON_COLUMN

DATABASE_NAME

String const DATABASE_NAME

DATABASE_VERSION

int const DATABASE_VERSION

Schema version. Version 1 databases (including CAMS 1.x) are migrated on init.

DEPLOYED_ON_COLUMN

String const DEPLOYED_ON_COLUMN

DEPLOYMENT_COLUMN

String const DEPLOYMENT_COLUMN

DEPLOYMENT_STATUS_COLUMN

String const DEPLOYMENT_STATUS_COLUMN

DEVICE_ROLE_NAME_COLUMN

String const DEVICE_ROLE_NAME_COLUMN

ID_COLUMN

String const ID_COLUMN

PARTICIPANT_ID_COLUMN

String const PARTICIPANT_ID_COLUMN

PARTICIPANT_ROLE_NAME_COLUMN

String const PARTICIPANT_ROLE_NAME_COLUMN

SAMPLING_STATUS_COLUMN

String const SAMPLING_STATUS_COLUMN

STUDY_DEPLOYMENT_ID_COLUMN

String const STUDY_DEPLOYMENT_ID_COLUMN

STUDY_ID_COLUMN

String const STUDY_ID_COLUMN

STUDY_TABLE_NAME

String const STUDY_TABLE_NAME

TASK_COLUMN

String const TASK_COLUMN

TASK_ID_COLUMN

String const TASK_ID_COLUMN

TASK_QUEUE_TABLE_NAME

String const TASK_QUEUE_TABLE_NAME

UPDATED_ON_COLUMN

String const UPDATED_ON_COLUMN

Properties

databaseName

String get databaseName

Full path and name of the database.

databasePath

String get databasePath

The folder holding the database. Set by init.

Methods

close

Future<void> close()

Closes the database. After this, no study or task can be read or saved.

getAllStudies

Future<List<SmartphoneStudy>> getAllStudies()

Get the list of all studies previously stored on this phone.

Returns an empty list if no studies are stored or loading fails.

getStudy

Future<SmartphoneStudy?> getStudy(
  1. String studyDeploymentId,
  2. String deviceRoleName
)

Return the SmartphoneStudy with studyDeploymentId and deviceRoleName, or null when no such study is found.

getUserTasks

Future<List<UserTaskSnapshot>> getUserTasks([
  1. SmartphoneStudy? study
])

Get the list of UserTaskSnapshot for study. If study is null, all user tasks are returned.

init

Future<void> init()

Opens (and if needed creates or migrates) the database, and starts saving study and task changes. Must be called before any other method.

removeStudy

Future<void> removeStudy(
  1. Study<PrimaryDeviceDeployment> study
)

Removes study from the database. Its user tasks are not removed; use removeUserTasks for that.

removeUserTasks

Future<void> removeUserTasks([
  1. Study<PrimaryDeviceDeployment>? study
])

Remove the list of user tasks for study. If study is null, all user tasks are removed.

saveStudy

Future<bool> saveStudy(
  1. SmartphoneStudy study
)

Saves study, replacing any existing row for it. Returns true if successful.

saveUserTask

Future<void> saveUserTask(
  1. UserTask task
)

Saves task to the task queue table, or deletes it if its state is UserTaskState.dequeued.

updateStudy

Future<bool> updateStudy(
  1. SmartphoneStudy study
)

Updates the stored study, matched on study deployment ID and device role name. Returns true if successful.