com.samsung.android.sdk.healthdata

Class HealthDataResolver

java.lang.Object

com.samsung.android.sdk.healthdata.HealthDataResolver

public class HealthDataResolver
extends Object

This class is able to access health data to insert, read, update, and delete with the specified filter and some aggregate functions.

Data Management

Health data can be accessed with following interfaces mainly.

• HealthDataResolver.InsertRequest
• HealthDataResolver.ReadRequest
• HealthDataResolver.UpdateRequest
• HealthDataResolver.DeleteRequest
• HealthDataResolver.AggregateRequest

Filter

Handling a part of data is a common use case rather than accessing whole data for the health data type. The Health data framework provides a filter to specify the precise scope for health data and is able to access required data only.

• HealthDataResolver.Filter

Asynchronous Data Request

The asynchronous request is used normally for operations that take a time such as reading data with conditions.
If you need to request asynchronously, set the result listener with HealthResultHolder.setResultListener(HealthResultHolder.ResultListener).

The following example shows how to make an asynchronous request.

 public class HealthDataResolverExample {

     // The state of connection
     HealthDataStore mStore;

     public static final String APP_TAG = "MyApp";

     public void readGlucoseAsynchronously(long startTime, long endTime) {

         HealthDataResolver resolver = new HealthDataResolver(mStore, null);

         HealthDataResolver.ReadRequest request = new HealthDataResolver.ReadRequest.Builder()
             .setDataType(HealthConstants.BloodGlucose.HEALTH_DATA_TYPE)
             .setLocalTimeRange(HealthConstants.BloodGlucose.START_TIME, HealthConstants.BloodGlucose.TIME_OFFSET,
                            startTime, endTime)
             .build();

         try {
             resolver.read(request).setResultListener(mRdResult);
         } catch (Exception e) {
             Log.d(APP_TAG, "Reading health data fails.");
         }
     }

     private final HealthResultHolder.ResultListener<HealthDataResolver.ReadResult> mRdResult =
         new HealthResultHolder.ResultListener<HealthDataResolver.ReadResult>(){

         @Override
         public void onResult(HealthDataResolver.ReadResult result) {

             try {
                 Iterator<HealthData> iterator = result.iterator();

                 if (iterator.hasNext()) {
                    HealthData data = iterator.next();
                    float glucoseValue = data.getFloat(HealthConstants.BloodGlucose.GLUCOSE);
             } finally {
                 result.close();
             }
     };
 }

Synchronous DataRequest

Though asynchronous data request is used commonly, there is a way to get the query result synchronously with HealthResultHolder.await().

Note, not to make the synchronous request on the UI thread. HealthResultHolder.await() throws an exception if it is called on the main thread. It can hang your application caused by taking a time to handle the synchronous query.

The following example shows how to make a synchronous request.

 public class HealthDataResolverExample {

     // The state of connection
     HealthDataStore mStore;

     public static final String APP_TAG = "MyApp";

     public void readGlucoseSynchronously(long startTime, long endTime) {
         HealthDataResolver resolver = new HealthDataResolver(mStore, null);

         HealthDataResolver.ReadRequest request = new HealthDataResolver.ReadRequest.Builder()
             .setDataType(HealthConstants.BloodGlucose.HEALTH_DATA_TYPE)
             .setLocalTimeRange(HealthConstants.BloodGlucose.START_TIME, HealthConstants.BloodGlucose.TIME_OFFSET,
                            startTime, endTime)
             .build();

         try {
             // Checks the result immediately
             HealthDataResolver.ReadResult rdResult = resolver.read(request).await();

             try {
                 Iterator<HealthData> iterator = rdResult.iterator();
                 if (iterator.hasNext()) {
                     HealthData data = iterator.next();
                     float glucoseValue = data.getFloat(HealthConstants.BloodGlucose.GLUCOSE);
                 }
             finally {
                 rdResult.close();
             }
         } catch (Exception e) {
             Log.d(APP_TAG, "Reading health data fails.");
         }
     }
 }

Acquiring Data Permission

Getting data permission is required after connection to the health data store to synchronize health data with Samsung Health. Samsung Health Android SDK provides the permission UI to get the user's consent. The user can agree to share health data with the application through the permission UI and the application can get required data permission Check HealthPermissionManager to use the permission UI.

If you try to read or write health data without permission, the SDK gives SecurityException.

Acquiring Instant Data Permission

Gaining the HealthConstants.HealthDocument type's permission is different with other data types. It is available by acquiring the instant permission.
Instant permission is created for one-time data access. It is proper to handle very sensitive health data. The data type needs the instant permission is HealthConstants.HealthDocument.
An app needs the instant permission whenever it accesses health document data.

• HealthDataResolver.insertWithPermission()
• HealthDataResolver.readWithPermission()
• HealthDataResolver.deleteWithPermission()

If you call HealthDataResolver.readWithPermission(), its permission pop-up is shown.
The user can select one or more health documents in the list and read the selected document.

Class Relationship of HealthDataResolver

The following class diagram shows the relationship of HealthDataResolver related classes.

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	HealthDataResolver.AggregateRequest This interface represents an aggregate request with aggregate functions and the specified time unit to group result values.
static class	HealthDataResolver.AggregateResult This class represents the result of HealthDataResolver.AggregateRequest.
static interface	HealthDataResolver.DeleteRequest This interface is able to make a request to delete health data for the specific health data type.
static class	HealthDataResolver.Filter This class creates a filter to make the request range clear.
static interface	HealthDataResolver.InsertRequest This interface is able to make a request to insert health data for the specific health data type.
static interface	HealthDataResolver.ReadRequest This interface is able to make a request to read health data for the specific health data type.
static class	HealthDataResolver.ReadResult This class represents the result for HealthDataResolver.ReadRequest.
static class	HealthDataResolver.SortOrder This enum defines sort orders.
static interface	HealthDataResolver.UpdateRequest This interface is able to make a request to update health data for the specific health data type.

Constructor Summary

Constructors

Constructor and Description
HealthDataResolver(HealthDataStore store, Handler handler) Creates a HealthDataResolver instance.

Method Summary

Modifier and Type	Method and Description
HealthResultHolder<HealthDataResolver.AggregateResult>	aggregate(HealthDataResolver.AggregateRequest request) Aggregates health data with the given request.
HealthResultHolder<HealthResultHolder.BaseResult>	delete(HealthDataResolver.DeleteRequest request) Deletes health data with the given request.
HealthResultHolder<HealthResultHolder.BaseResult>	deleteWithPermission(HealthDataResolver.DeleteRequest request, Activity activity) Deletes health data required instant permission with the given request.
HealthResultHolder<HealthResultHolder.BaseResult>	insert(HealthDataResolver.InsertRequest request) Inserts new health data with the given request.
HealthResultHolder<HealthResultHolder.BaseResult>	insertWithPermission(HealthDataResolver.InsertRequest request, Activity activity) Inserts new health data required instant permission with the given request.
HealthResultHolder<HealthDataResolver.ReadResult>	read(HealthDataResolver.ReadRequest request) Reads health data with the given request.
HealthResultHolder<HealthDataResolver.ReadResult>	readWithPermission(HealthDataResolver.ReadRequest request, Activity activity) Reads health data required instant permission with the given request.
HealthResultHolder<HealthResultHolder.BaseResult>	update(HealthDataResolver.UpdateRequest request) Updates health data with the given request.

Constructor Detail

HealthDataResolver

public HealthDataResolver(HealthDataStore store,
                          Handler handler)

Creates a HealthDataResolver instance.

Parameters:

store - The health data store for connection

handler - The handler for the proceeding thread. If it's null, the looper of the current thread will be used.

Since:

1.0.0

Method Detail

insert

public HealthResultHolder<HealthResultHolder.BaseResult> insert(HealthDataResolver.InsertRequest request)

Inserts new health data with the given request.
It can be implemented asynchronously or synchronously.
If the given request does not specify required information, e.g. the data source, it fails.

Parameters:

request - The request to insert new health data

Returns:

The HealthResultHolder instance which resolves to the HealthResultHolder.BaseResult for inserted health data

Throws:

IllegalArgumentException - If the request contains invalid instance type, null, BLOB data size is bigger than 1000KB or too large data

SecurityException - If there is no permission to write for given health data

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.0.0

insertWithPermission

public HealthResultHolder<HealthResultHolder.BaseResult> insertWithPermission(HealthDataResolver.InsertRequest request,
                                                                              Activity activity)

Inserts new health data required instant permission with the given request. Calling this method, a file chooser is shown to acquire the user consent. After the user chooses all or some of files, those are finally inserted.
It can be implemented asynchronously or synchronously.
If the given request does not specify required information, e.g. the data source, it fails.

Parameters:

request - The request to insert new health data

activity - The activity that pop up the permission UI

Returns:

The HealthResultHolder instance which resolves to the HealthResultHolder.BaseResult for inserted health data

Throws:

IllegalArgumentException - If the request contains invalid instance type, null, and file size is bigger than about 10MB.

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.3.0

update

public HealthResultHolder<HealthResultHolder.BaseResult> update(HealthDataResolver.UpdateRequest request)

Updates health data with the given request.
It can be implemented asynchronously or synchronously.

Parameters:

request - The request to update health data

Returns:

The HealthResultHolder instance which resolves to the HealthResultHolder.BaseResult for updated health data

Throws:

IllegalArgumentException - If the request contains invalid instance type or null, BLOB data size is bigger than 1000KB or too large data

SecurityException - If there is no permission to write for given health data

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.0.0

delete

public HealthResultHolder<HealthResultHolder.BaseResult> delete(HealthDataResolver.DeleteRequest request)

Deletes health data with the given request.
It can be implemented asynchronously or synchronously.

Parameters:

request - The request to delete health data

Returns:

The HealthResultHolder instance which resolves to the HealthResultHolder.BaseResult for deleted health data

Throws:

IllegalArgumentException - If the request contains invalid instance type or null

SecurityException - If there is no permission to write for given health data

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.0.0

deleteWithPermission

public HealthResultHolder<HealthResultHolder.BaseResult> deleteWithPermission(HealthDataResolver.DeleteRequest request,
                                                                              Activity activity)

Deletes health data required instant permission with the given request. Calling this method, a file chooser is shown to acquire the user consent. After the user chooses all or some of files, those are finally deleted.
It can be implemented asynchronously or synchronously.

Parameters:

request - The request to delete health data

activity - The activity that pop up the permission UI

Returns:

The HealthResultHolder instance which resolves to the HealthResultHolder.BaseResult for deleted health data

Throws:

IllegalArgumentException - If the request contains invalid instance type or null

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.3.0

read

public HealthResultHolder<HealthDataResolver.ReadResult> read(HealthDataResolver.ReadRequest request)

Reads health data with the given request.
It can be implemented asynchronously or synchronously.

Parameters:

request - The request to read health data

Returns:

The HealthResultHolder instance which resolves to the HealthDataResolver.ReadResult for health data to read

Throws:

IllegalArgumentException - If the request contains invalid instance type or null

SecurityException - If there is no permission to read for given health data

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.0.0

readWithPermission

public HealthResultHolder<HealthDataResolver.ReadResult> readWithPermission(HealthDataResolver.ReadRequest request,
                                                                            Activity activity)

Reads health data required instant permission with the given request. Calling this method, a file chooser is shown to acquire the user consent. After the user chooses all or some of files, those are finally read.
It can be implemented asynchronously or synchronously.

Parameters:

request - The request to read health data

activity - The activity that pop up the permission UI

Returns:

The HealthResultHolder instance which resolves to the HealthDataResolver.ReadResult for health data to read

Throws:

IllegalArgumentException - If the request contains invalid instance type or null

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.3.0

aggregate

public HealthResultHolder<HealthDataResolver.AggregateResult> aggregate(HealthDataResolver.AggregateRequest request)

Aggregates health data with the given request.
It can be implemented asynchronously or synchronously.

Parameters:

request - The aggregate request for health data

Returns:

The HealthDataResolver.AggregateResult instance which resolves to the HealthDataResolver.ReadResult for the requested aggregate

Throws:

IllegalArgumentException - If the request contains invalid instance type or null

SecurityException - If there is no permission to read for given health data

IllegalStateException - If the instance of health data store is invalid or a remote-invocation error occurs on the connection

Since:

1.0.0