Skip to content
CARP Documentation

CarpBaseService

Base class for all CAWS client services.

Holds the shared state and plumbing of CarpService, CarpParticipationService, CarpDeploymentService, CarpProtocolService and CarpDataStreamService: the CarpApp to talk to, an optional study, authenticated headers and the HTTP/RPC calls.

Key points:

  • Call configure (or configureFrom) before use, or app throws.
  • Requests use the access token of CarpAuthService.currentUser.
  • The REST helpers (GET, POST, PUT, DELETE) refresh the token once after a 403 response and retry. RPC requests and file-transfer tasks do not.
  • Network errors are retried by HTTPRetry. Error responses with a JSON body are thrown as CarpServiceRequestExceptions; transport and response-decoding errors can propagate as they are.

Each app is assumed to connect to one CAWS backend only, so the default constructors return shared instances, used like:

await CarpAuthService().configure(authProperties);

var user = await CarpAuthService().authenticateWithUsernamePassword(
  username: username,
  password: password,
);

 final app = CarpApp(
    name: 'CAWS DEV',
    uri: Uri(
      scheme: 'https',
      host: 'dev.carp.dk',
    ));

CarpParticipationService().configure(app);

where authProperties, username, and password set up authentication, and app points the participation service to the right CAWS instance.

Implementers

Constructors

CarpBaseService

CarpBaseService()

Properties

app

CarpApp get app

The CAWS instance this service talks to.

Throws a CarpServiceException if this service has not yet been configured via the configure method.

headers

Map<String, String> get headers

The headers for any authenticated HTTP REST call to a CarpBaseService.

Holds the bearer access token of CarpAuthService.currentUser. Throws a CarpServiceException if the user has no token.

isConfigured

bool get isConfigured

Has this service been configured?

rpcEndpointName

String get rpcEndpointName

The name of this service's RPC endpoint at CAWS, like deployment-service.

rpcEndpointUri

String get rpcEndpointUri

The URL of the endpoint used by the latest RPC request.

Typically on the form: {{PROTOCOL}}://{{SERVER_HOST}}:{{SERVER_PORT}}/api/...

study

SmartphoneStudy? study
getter/setter pair

The study this service is tied to, if any.

Used as the default for study, study deployment and device role IDs that are not passed explicitly. Can be set directly or via configure.

Methods

configure

void configure(
  1. CarpApp app, [
  2. SmartphoneStudy? study
])

Configures this service.

The app specifies the CAWS instance used. If study is specified, this service is 'tied' to this study deployment. This is convenient if the app only handles one study deployment (which is often the case).

configureFrom

void configureFrom(
  1. CarpBaseService service
)

Copies app and study from another service that is already configured.

getPrimaryDeviceRoleName

String getPrimaryDeviceRoleName([
  1. String? deviceRoleName
])

Resolves the primary device role name.

Returns deviceRoleName if not null. Otherwise returns the device role name of study, if available. Throws a CarpServiceException if the role name cannot be resolved.

getStudyDeploymentId

String getStudyDeploymentId([
  1. String? studyDeploymentId
])

Resolves a study deployment ID.

Returns studyDeploymentId if not null. Otherwise returns the study deployment ID of study, if available. Throws a CarpServiceException if the ID cannot be resolved.

getStudyId

String getStudyId([
  1. String? studyId
])

Resolves a study ID.

Returns studyId if not null. Otherwise returns the study ID of study, if available. Throws a CarpServiceException if the study ID cannot be resolved.

toString

String toString()
override

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.