Syncing with Remote Tables

ActiveRecordCloudSync is a library built for this project that syncs local active record models on the Android device with a remote API. This is to ensure data is not lost and that data is available in situations where there is sparse internet access. ActiveRecordCloudSync is designed to work with ActiveAndroid, but there is no reason you can't roll your own ActiveRecord implementation and use ActiveRecordCloudSync to do the heavy-lifting of keeping your databases in sync.

Adding a ReceiveTable

A ReceiveModel grabs data from a remote source and stores it in the device's local database through ActiveRecord models. You must tell ActiveRecordCloudSync where the API endpoint for your remote data is before use.

ActiveRecordCloudSync.setEndPoint("http://endpoint.com/api/v1/");

You must also add each ReceiveModel so that ActiveRecordCloudSync is aware of its existence. You provide the remote table name, and it will be accessed in a RESTful manner using the specified api end point (your end point + your remote table).

// This will expect a JSON list of items at http://endpoint.com/api/v1/remote_table
ActiveRecordCloudSync.addReceiveTable("remote_table", RemoteTable.class);

In order for your ActiveRecord class to be added to the ReceiveModel list, it must extend the ReceiveModel abstract class. The ReceiveModel interface requires createObjectFromJSON(JSONObject). When ActiveRecordCloudSync receives a json object from your api, it injects it into this method as a JSONObject. Typically this is where you would want to set the fields for a model instance and save.

For example:

@Table(name = "RemoteTables")
public class RemoteTable extends ReceiveModel {
    @Column(name = "Value")
    private String mValue;

    public void setValue(String v) {
        mValue = v;
    }

    @Override
    public void createObjectFromJSON(JSONObject jsonObject) {
        try {
                setValue(jsonObject.getString("value");
                this.save();
            }
        } catch (JSONException je) {
            Log.e(TAG, "Error parsing object json", je);
        }  
    }
}

A SendModel sends data from the device to a remote table. Using SendModel is very similar to using ReceiveModel. You must extend the SendModel abstract class on your ActiveRecord model.

A SendModel requires the following methods:

public JSONObject toJSON();
public boolean isSent();
public boolean readyToSend();
public void setAsSent();

toJson() should return a JSON representation of a model instance. This is what is POSTed to your API end point. isSent() and setAsSent() keep track of if the data has already been sent to the remote table. readyToSend() returns a boolean indicating if the instance is ready to be sent to the server.

You must also add the SendModel to the SendTable list.

ActiveRecordCloudSync.addSendTable("remote_table", RemoteTable.class);

Polling

ActiveRecordCloudSync uses polling to keep everything up to date. To do this, it uses the built in AlarmManager provided by Android. This ensures that the process continues in the absence of any of your activities.

To enable polling:

PollService.setServiceAlarm(getActivity(), true);

To disable polling:

PollService.setServiceAlarm(getActivity(), false);

To override the default polling interval in milliseconds (default currently 15 seconds):

PollService.setPollInterval(int interval)

Quick Start

To get started quickly, add the following to the onCreate of your main activity (or one of its fragments):

ActiveRecordCloudSync.setEndPoint("http://endpoint.com/api/v1/");
ActiveRecordCloudSync.addReceiveTable("remote_table", RemoteTable.class);
ActiveRecordCloudSync.addSendTable("local_to_remote_table", LocalToRemoteTable.class);
PollService.setServiceAlarm(getActivity(), true);