carp_webservices 0.2.1

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 73

CARP Web Service Plugin for Flutter #

A Flutter plugin to access the CARP Web Service API.

pub package

For Flutter plugins for other CARP products, see CARP Mobile Sensing in Flutter.

Note: This plugin is still under development, and some APIs might not be available yet. Feedback and Pull Requests are most welcome!

Setup #

  1. You need a CARP Web Service host running. See the CARP Web Service API documentation for how to do this. If you're part of the CACHET team, you can use the specified development, staging, and production servers.

  2. Add carp_services as a dependency in your pubspec.yaml file.

Usage #

import 'package:carp_webservices/carp_service/carp_service.dart';

Configuration #

The CarpService is a singleton and needs to be configured once. Note that a valid Study with a valid study ID is needed.

final String uri = "http://staging.carp.cachet.dk:8080";

CarpApp app;
Study study;

study = new Study(testStudyId, "user@dtu.dk", name: "Test study #$testStudyId");
app = new CarpApp(
      study: study,
      name: "any_display_friendly_name_is_fine",
      uri: Uri.parse(uri),
      oauth: OAuthEndPoint(clientID: "the_client_id", clientSecret: "the_client_secret"));

CarpService.configure(app);

The singleton can then be accessed via CarpService.instance.

Authentication #

Authentication is currently only supported using username and password.

CarpUser user;
try {
   user = await CarpService.instance.authenticate(username: "a_username", password: "the_password");
} catch (excp) {
   ...;
}

Data Points #

A DataPointReference is used to manage data points on a CARP web service and have CRUD methods for:

  • post a data point
  • batch upload multiple data points
  • get a data point
  • delete data points
// Create a test location datum
LocationDatum datum = LocationDatum.fromMap(<String, dynamic>{
  "latitude": 23454.345,
  "longitude": 23.4,
  "altitude": 43.3,
  "accuracy": 12.4,
  "speed": 2.3,
  "speedAccuracy": 12.3
});

// create a CARP data point
final CARPDataPoint data = CARPDataPoint.fromDatum(study.id, study.userId, datum);
// post it to the CARP server, which returns the ID of the data point
data_point_id = await CarpService.instance.getDataPointReference().postDataPoint(data);

// get the data point back from the server
CARPDataPoint data = await CarpService.instance.getDataPointReference().getDataPoint(data_point_id);

// batch upload a list of raw json data points in a file
final File file = File("test/batch.json");
await CarpService.instance.getDataPointReference().batchPostDataPoint(file);

// delete the data point
await CarpService.instance.getDataPointReference().deleteDataPoint(data_point_id);

Application-specific Collections and Documents #

A CollectionReference is used to manage collections on a CARP web service and have methods for:

  • creating, updating, and deleting documents
  • accessing documents in collections
  // access an document
  //  - if the document id is not specified, a new document (with a new id) is created
  //  - if the collection (users) don't exist, it is created
  DocumentSnapshot document =
      await CarpService.instance.collection('users').document().setData({'email': username, 'name': 'Administrator'});

  // update the document
  DocumentSnapshot updated_document = await CarpService.instance
      .collection('/users')
      .document(document.name)
      .updateData({'email': username, 'name': 'Super User'});

  // get the document
  DocumentSnapshot new_document = await CarpService.instance.collection('users').document(document.name).get();

  // delete the document
  await CarpService.instance.collection('users').document(document.name).delete();

  // get all collections from a document
  List<String> collections = new_document.collections;

  // get all documents in a collection.
  List<DocumentSnapshot> documents = await CarpService.instance.collection("users").documents;

File Management #

A FileStorageReference is used to manage files on a CARP web service and have methods for:

  • uploading a file
  • downloading a file
  • getting a file object
  • getting all file objects
  • deleting a file

When uploading a file, you can add metadata as a Map<String, String>.

// first upload a file
final File myFile = File("test/img.jpg");
final FileUploadTask uploadTask = CarpService.instance
   .getFileStorageReference()
   .upload(myFile, {'content-type': 'image/jpg', 'content-language': 'en', 'activity': 'test'});
CarpFileResponse response = await uploadTask.onComplete;
int id = response.id;

// then get its description back from the server
final CarpFileResponse result = await CarpService.instance.getFileStorageReference(id).get();

// then download the file again
// note that a local file to download is needed
final File myFile = File("test/img-$id.jpg");
final FileDownloadTask downloadTask = CarpService.instance.getFileStorageReference(id).download(myFile);
int response = await downloadTask.onComplete;

// now get references to ALL files in this study
final List<CarpFileResponse> results = await CarpService.instance.getFileStorageReference(id).getAll();

// finally, delete the file
final int result = await CarpService.instance.getFileStorageReference(id).delete();

Features and bugs #

Please file feature requests and bug reports at the issue tracker.

License #

This software is copyright (c) 2018 Copenhagen Center for Health Technology (CACHET) at the Technical University of Denmark (DTU). This software is made available 'as-is' in a MIT license.

0.2.1 #

  • support for get document by id

0.2.0 #

  • upgrade and test on Flutter v. 1.3.4 Dart v. 2.2.1
  • upgrading to the new CARP Web Service API for documents (instead of objects) and collections

0.1.3 #

  • Adjustment to refactoring of carp_mobile_sensing library to version 0.3.0

0.1.2 #

  • Small refactor and removal of debug print.
  • Adding an example
  • Added support for batch upload of data points as a file.

0.1.1 #

  • Documentation update.

0.1.0 #

  • Initial release.

example/example.dart

import 'package:carp_webservices/carp_auth/carp_auth.dart';
import 'package:carp_webservices/carp_service/carp_service.dart';
import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
import 'dart:io';

void main() async {
  final String username = "researcher";
  final String password = "password";
  final String uri = "http://staging.carp.cachet.dk:8080";
  final String clientID = "carp";
  final String clientSecret = "carp";
  final String testStudyId = "8";

  CarpApp app;
  Study study;

  study = new Study(testStudyId, "user@dtu.dk", name: "Test study #$testStudyId");
  app = new CarpApp(
      study: study,
      name: "any_display_friendly_name_is_fine",
      uri: Uri.parse(uri),
      oauth: OAuthEndPoint(clientID: "the_client_id", clientSecret: "the_client_secret"));

  // Configure the CARP Service with this app.
  CarpService.configure(app);

  // ------------------- AUTHENTICATION --------------------------------

  // Try to authenticate
  CarpUser user;
  try {
    user = await CarpService.instance.authenticate(username: "a_username", password: "the_password");
  } catch (excp) {
    print(excp);
  }

  // ------------------- FILE MANAGEMENT --------------------------------

  // first upload a file
  final File uploadFile = File("test/img.jpg");
  final FileUploadTask uploadTask = CarpService.instance
      .getFileStorageReference()
      .upload(uploadFile, {'content-type': 'image/jpg', 'content-language': 'en', 'activity': 'test'});
  CarpFileResponse response = await uploadTask.onComplete;
  int id = response.id;

  // then get its description back from the server
  final CarpFileResponse result = await CarpService.instance.getFileStorageReference(id).get();

  // then download the file again
  // note that a local file to download is needed
  final File downloadFile = File("test/img-$id.jpg");
  final FileDownloadTask downloadTask = CarpService.instance.getFileStorageReference(id).download(downloadFile);
  int responseCode = await downloadTask.onComplete;

  // now get references to ALL files in this study
  final List<CarpFileResponse> results = await CarpService.instance.getFileStorageReference(id).getAll();

  // finally, delete the file
  responseCode = await CarpService.instance.getFileStorageReference(id).delete();

  // ------------------- DATA POINTS --------------------------------

  // Create a test bluetooth datum
  BluetoothDatum datum = BluetoothDatum()
    ..bluetoothDeviceId = "weg"
    ..bluetoothDeviceName = "ksjbdf"
    ..connectable = true
    ..txPowerLevel = 314
    ..rssi = 567
    ..bluetoothDeviceType = "classic";

  // create a CARP data point
  final CARPDataPoint data = CARPDataPoint.fromDatum(study.id, study.userId, datum);
  // post it to the CARP server, which returns the ID of the data point
  int data_point_id = await CarpService.instance.getDataPointReference().postDataPoint(data);

  // get the data point back from the server
  CARPDataPoint data_point = await CarpService.instance.getDataPointReference().getDataPoint(data_point_id);

  // batch upload a list of raw json data points in a file
  final File file = File("test/batch.json");
  await CarpService.instance.getDataPointReference().batchPostDataPoint(file);

  // delete the data point
  await CarpService.instance.getDataPointReference().deleteDataPoint(data_point_id);

  // ------------------- COLLECTIONS AND DOCUMENTS --------------------------------

  // access an document
  //  - if the document id is not specified, a new document (with a new id) is created
  //  - if the collection (users) don't exist, it is created
  DocumentSnapshot document =
      await CarpService.instance.collection('users').document().setData({'email': username, 'name': 'Administrator'});

  // update the document
  DocumentSnapshot updated_document = await CarpService.instance
      .collection('/users')
      .document(document.name)
      .updateData({'email': username, 'name': 'Super User'});

  // get the document
  DocumentSnapshot new_document = await CarpService.instance.collection('users').document(document.name).get();

  // delete the document
  await CarpService.instance.collection('users').document(document.name).delete();

  // get all collections from a document
  List<String> collections = new_document.collections;

  // get all documents in a collection.
  List<DocumentSnapshot> documents = await CarpService.instance.collection("users").documents;
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  carp_webservices: ^0.2.1

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter packages get

Alternatively, your editor might support flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:carp_webservices/carp_service/carp_datapoint.dart';
import 'package:carp_webservices/carp_service/carp_service.g.dart';
import 'package:carp_webservices/carp_auth/carp_auth.dart';
import 'package:carp_webservices/carp_auth/carp_user.dart';
import 'package:carp_webservices/carp_auth/oauth.dart';
import 'package:carp_webservices/carp_service/carp_app.dart';
import 'package:carp_webservices/carp_service/carp_service.dart';
import 'package:carp_webservices/carp_service/carp_tasks.dart';
import 'package:carp_webservices/carp_service/datapoint_reference.dart';
import 'package:carp_webservices/carp_service/document_reference.dart';
import 'package:carp_webservices/carp_service/file_reference.dart';
import 'package:carp_webservices/carp_service/push_id_generator.dart';
  
Version Uploaded Documentation Archive
0.2.1 Mar 18, 2019 Go to the documentation of carp_webservices 0.2.1 Download carp_webservices 0.2.1 archive
0.2.0 Mar 11, 2019 Go to the documentation of carp_webservices 0.2.0 Download carp_webservices 0.2.0 archive
0.1.3 Jan 21, 2019 Go to the documentation of carp_webservices 0.1.3 Download carp_webservices 0.1.3 archive
0.1.2 Dec 17, 2018 Go to the documentation of carp_webservices 0.1.2 Download carp_webservices 0.1.2 archive
0.1.1 Dec 11, 2018 Go to the documentation of carp_webservices 0.1.1 Download carp_webservices 0.1.1 archive
0.1.0 Dec 10, 2018 Go to the documentation of carp_webservices 0.1.0 Download carp_webservices 0.1.0 archive
Popularity:
Describes how popular the package is relative to other packages. [more]
46
Health:
Code health derived from static analysis. [more]
99
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
73
Learn more about scoring.

We analyzed this package on Apr 22, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.2.0
  • pana: 0.12.14
  • Flutter: 1.4.7

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Health suggestions

Fix lib/carp_service/carp_app.dart. (-0.50 points)

Analysis of lib/carp_service/carp_app.dart reported 1 hint:

line 38 col 11: Always override hashCode if overriding ==.

Fix lib/carp_service/datapoint_reference.dart. (-0.50 points)

Analysis of lib/carp_service/datapoint_reference.dart reported 1 hint:

line 150 col 8: The function '_encode' isn't used.

Format lib/carp_auth/carp_user.dart.

Run flutter format to format lib/carp_auth/carp_user.dart.

Fix additional 7 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/carp_auth/oauth.dart (Run flutter format to format lib/carp_auth/oauth.dart.)
  • lib/carp_service/carp_datapoint.dart (Run flutter format to format lib/carp_service/carp_datapoint.dart.)
  • lib/carp_service/carp_service.dart (Run flutter format to format lib/carp_service/carp_service.dart.)
  • lib/carp_service/carp_tasks.dart (Run flutter format to format lib/carp_service/carp_tasks.dart.)
  • lib/carp_service/document_reference.dart (Run flutter format to format lib/carp_service/document_reference.dart.)
  • lib/carp_service/file_reference.dart (Run flutter format to format lib/carp_service/file_reference.dart.)
  • lib/carp_service/push_id_generator.dart (Run flutter format to format lib/carp_service/push_id_generator.dart.)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
carp_mobile_sensing ^0.3.0 0.3.10
flutter 0.0.0
http ^0.12.0 0.12.0+2
json_annotation ^1.0.0 1.2.0 2.2.0
Transitive dependencies
app_usage 0.1.0
archive 2.0.8
args 1.5.1
async 2.2.0
battery 0.2.3 0.3.0+3
charcode 1.1.2
collection 1.14.11
connectivity 0.3.2 0.4.3+1
convert 2.1.1
crypto 2.0.6
device_apps 1.0.7
device_info 0.2.1 0.4.0+1
file_utils 0.1.1
fixnum 0.10.9
flutter_blue 0.4.2 0.5.0
globbing 0.2.0
http_parser 3.1.3
light 0.1.1
meta 1.1.6 1.1.7
path 1.6.2
path_provider 0.4.1 0.5.0+1
pedantic 1.5.0
pedometer 0.0.5
protobuf 0.10.8 0.13.11
screen_state 0.1.1
sensors 0.3.5 0.4.0+1
simple_permissions 0.1.9
sky_engine 0.0.99
source_span 1.5.5
stats 0.2.0+2
string_scanner 1.0.4
system_info 0.1.1
term_glyph 1.1.0
typed_data 1.1.6
uuid 1.0.3 2.0.1
vector_math 2.0.8
Dev dependencies
build_runner any
flutter_test
json_serializable ^1.0.0
test any