ClientManager
Manages the studies that run on a client device.
A client manager is the entry point of the client subsystem. It registers the device in study deployments, keeps track of the Studys on this device, and fetches their PrimaryDeviceDeployment from a DeploymentService.
Key points:
- Call configure once with a DeviceRegistration before any other call; most methods throw NotConfiguredException until then.
- Study lifecycle: addStudy -> tryDeployment (repeat until StudyStatus.Running) -> stopStudy or removeStudy.
- Deployment calls are delegated to a StudyDeploymentProxy; state is persisted in a ClientRepository.
- Subclasses overriding a lifecycle method must call
super.
See also SmartphoneClient. In CARP Mobile Sensing, SmartPhoneClientManager extends this class and also runs the studies.
- Implementers
Constructors
ClientManager
- ClientRepository<
TStudy> ? repository, - DeploymentService? deploymentService,
- DeviceDataCollectorFactory? dataCollectorFactory,
Create a new ClientManager.
repository is used to persist the state of this client. deploymentService is used to manage study deployments. dataCollectorFactory determines which DeviceDataCollector to use to collect data locally on this primary device and is used to create ConnectedDeviceDataCollector instances for connected devices.
Properties
dataCollectorFactory
Determines which DeviceDataCollector to use to collect data locally on this primary device and this factory is used to create ConnectedDeviceDataCollector instances for connected devices.
deploymentService
The application service through which study deployments, to be run on this client, can be managed and retrieved.
Throws NotConfiguredException if not set via the constructor or configure.
isConfigured
Determines whether a DeviceRegistration has been configured for this client, which is necessary to start adding studies.
proxy
Performs deployment calls for studies; created by configure.
registration
The registration of this client, set by configure.
Throws NotConfiguredException before configure is called.
repository
Repository within which the state of this client is stored.
Throws NotConfiguredException if no repository was given to the constructor.
studies
Get the studies running on this client device.
Methods
addStudy
- TStudy study
Add a study which needs to be executed on this client. No deployment is attempted yet.
If a study with the same deployment id and device role name has already been added to this client, it is not added again and no status is fetched. The study passed in is returned, which can be a different instance from the one already stored.
Throws NotConfiguredException if the client has not yet been configured. Returns the study added to this client manager or the existing study if it was already added.
configure
- required TRegistration registration,
- DeploymentService? deploymentService,
- DeviceDataCollectorFactory? dataCollectorFactory,
Configure this ClientManager by specifying a registration for this client device.
Optionally, you can specify or override:
deploymentService- where to get study deploymentsdataCollectorFactory- the factory for creating data collectors
Throws an AssertionError if this client manager has already been configured. Throws NotConfiguredException if after configuration either deploymentService or dataCollectorFactory is not set.
getStudy
Get the study with studyDeploymentId and deviceRoleName from this client manager. Returns null if no such study has been added.
getStudyDeploymentStatus
- TStudy study
Get the deployment status for the study from the deployment service. This updates the study's deployment status and sets the study's status accordingly. Returns null if the deployment status could not be retrieved from the deployment service or if the study has not been added to this client manager.
getStudyStatusList
Get the status for the studies which run on this client device. Note that this is the latest known status, held locally. If you want an updated status from the deployment service, use getStudyDeploymentStatus for each study.
removeStudy
Remove the study with studyDeploymentId and deviceRoleName from this client manager.
Note that by removing a study, the deployment is not marked as stopped permanently in the deployment service. Hence, the study can later be added and deployed again using the addStudy and tryDeployment methods.
If a study deployment is to be permanently stopped, use the stopStudy method.
stopStudy
Permanently stop collecting data for the study with id studyDeploymentId and mark it as stopped.
Once a study is stopped it cannot be deployed anymore since it will be marked as permanently stopped in the deployment service.
If you want to remove the study from this client and be able to redeploy it later, use the removeStudy method instead. Note that stopping a study does not remove it from this client manager.
Throws IllegalArgumentException if no such study has been added. Returns the new StudyStatus of the study.
tryDeployment
Verifies whether the device is ready for deployment of the study runtime identified by studyDeploymentId and deviceRoleName, and in case it is, deploys. Also runs for a study that is already deployed, to refresh its deployment information. Returns the study's status afterwards.
Throws NotConfiguredException if the client has not yet been configured. Throws IllegalArgumentException if a study with the given studyDeploymentId and deviceRoleName has not been added. Most other deployment failures do not throw; they are reported on the study as StudyStatusEventTypes.DeploymentError events.
Returns the new StudyStatus of the study.