Getting familiar with the sdk

Learn about what are the RM and RookMotion classes.

---

Contents

1. The RM class
   1. Callbacks and response
2. The RookMotion class
   1. Result types
3. Next steps

---

The RM class

The RM class allows you easy access to all Java features, it is a combination of low level classes and resources (Database, Api, etc.)

You can access those resources by yourself but the RM class already takes care of complex operations like Database and Api updates, Api response formatting, etc.

We strongly encourage you to ONLY USE RM CLASS.

Deprecations

We are in the process of migrating or features to the Kotlin language so in the future you may see some RM functions annotated with @Deprecated, it means that there is a better implementation on the Kotlin side (RookMotion class). And you should change to that as soon as possible, as that function will be removed in the near feature in a breaking update.

Callbacks and responses

The RM class uses callbacks to notify about an operation response.

There are two types of callbacks:

RMCallback

This callback represents an operation response without data.

public interface RMCallback {
    void onFinish(RMResponse rmResponse);
}

RMGenericCallback

This callback represents an operation response containing data. When the expected type is not a list, assume the result is nullable.

public interface RMGenericCallback<R> {
    void onFinish(RMResponse rmResponse, R result);
}

The only thing in common is that both return an RMResponse object, you can use this object to check if an operation was successful or know why it failed.

public class RMResponse {

    private String code;        // HTTP response code if the operation made a web service request. Otherwise, it will return 000 for successful or 0 for unsuccessful local operations.
    private String message;     // Reason of failure or success confirmation
    private boolean success;    // Flag indicating if the operation was successful
}

---

The RookMotion class

The RookMotion class is the main dependency of all Kotlin features, which are divided in other RMModules ( RMRemote, RMSummaries, etc.), which use low level classes and resources (Database, Api, etc.)

You can access those resources by yourself but the RookMotion class, and it's modules already take care of complex operations like; Database and Api updates, Api response formatting, etc.

We strongly encourage you to ONLY USE RookMotion class AND RMModules

Result types

RMModules functions are suspend and return sealed classes to notify about an operation result.

There are two types of results:

BasicResult

This sealed class represents a function result without data.

sealed class BasicResult {

    object Success

    // code: HTTP code | error: HTTP error response body
    class Error(val code: Int, val error: String)
}

DataResult

This sealed class represents a function result containing data.

sealed class DataResult {

    // code: HTTP code | data: HTTP response body
    class Success(val code: Int, val data: T)

    // code: HTTP code | error: HTTP error response body
    class Error(val code: Int, val error: String)
}

UTC

All timestamps and date strings of Rook Training SDK (with some exceptions) are in UTC, to adjust our strings to your user's time zone.

Our sdk-utils library uses JodaTime to perform these adjustments. Call UTCConverter.getDateTime providing the date string and a flag indicating if the string is in UTC.

UTCConverter.getDateTime("2022-11-08 19:08:09", true)

It will return a DateTime object adjusted to the device's time zone. Or null on error. (If you have Timber logs enabled the error will be logged).

Exceptions

If you are a new client in this SDK you can ignore the following. If you have used this SDK before November 2022 it's possible that we have some trainings of your users which are not in UTC, so when requesting the training history list or detail you MUST find out if the training is in UTC or not.

When you request a list of trainings or the details of a training from server it will contain an additional property

deviceOffset <- Available on TrainingListObject and RMTrainingInformation objects

If this property is null it means that this is NOT a UTC training, so you'll call UTCConverter.getDateTime like:

UTCConverter.getDateTime("2022-11-08 19:08:09", false)

On the other side if the property is non-null it will return a string with the offset the training was sent with, you can use this offset to show the appropriate date to your end-users.

Although our recommendation is to only check if the property is non-null, then instead of using the returned offset call UTCConverter.getDateTime like:

UTCConverter.getDateTime("2022-11-08 19:08:09", true)

Remember, the deviceOffset property indicates offset for the following properties:

• TrainingListObject start and end
• RMTrainingInformation start and end
• RMHrDerivedRecord timestamp
• RMStepDerivedRecord timestamp
• RMBicycleDerivedRecord timestamp

Next steps

Now you are ready to start coding go to the next tutorial to learn How to authenticate a user.