Parse LiveQuery Client for Android

ParseQuery is one of the key concepts for Parse. It allows you to retrieve ParseObjects by specifying some conditions, making it easy to build apps such as a dashboard, a todo list or even some strategy games. However, ParseQuery is based on a pull model, which is not suitable for apps that need real-time support.

Suppose you are building an app that allows multiple users to edit the same file at the same time. ParseQuery would not be an ideal tool since you can not know when to query from the server to get the updates.

To solve this problem, we introduce Parse LiveQuery. This tool allows you to subscribe to a ParseQuery you are interested in. Once subscribed, the server will notify clients whenever a ParseObject that matches the ParseQuery is created or updated, in real-time.

Setup Server

Parse LiveQuery contains two parts, the LiveQuery server and the LiveQuery clients. In order to use live queries, you need to set up both of them.

The easiest way to setup the LiveQuery server is to make it run with the Open Source Parse Server.

Setup Client

Download the latest JAR or define in Gradle:

dependencies {
  compile 'com.parse:parse-livequery-android:0.0.1'
}

Snapshots of the development version are available in Sonatype's snapshots repository.

Use Client

The LiveQuery client interface is based around the concept of Subscriptions. You can register any ParseQuery for live updates from the associated live query server, by simply calling subscribe() on a the client:

ParseLiveQueryClient<ParseObject> parseLiveQueryClient = ParseLiveQueryClient.Factory.get(URI);
SubscriptionHandling<ParseObject> subscriptionHandling = parseLiveQueryClient.subscribe(parseQuery)

Once you've subscribed to a query, you can handle events on them, like so:

subscriptionHandling.handleEvents(new SubscriptionHandling.HandleEventsCallback<ParseObject>() {
    @Override
    public void onEvents(ParseQuery<ParseObject> query, SubscriptionHandling.Event event, ParseObject object) {
        // HANDLING all events
    }
})

You can also handle a single type of event, if that's all you're interested in:

subscriptionHandling.handleEvent(SubscriptionHandling.Event.CREATE, new SubscriptionHandling.HandleEventCallback<ParseObject>() {
    @Override
    public void onEvent(ParseQuery<ParseObject> query, ParseObject object) {
        // HANDLING create event
    }
})

Handling errors is and other events is similar, take a look at the SubscriptionHandling class for more information.

Advanced Usage

You are not limited to a single Live Query Client - you can create your own instances of Client to manually control things like reconnecting, server URLs, and more.

Build commands

Everything can done through the supplied gradle wrapper:

Compile a JAR

./gradlew clean jarRelease

Outputs can be found in ParseLiveQuery/build/libs/

Run the Tests

./gradlew clean testDebug

Results can be found in ParseLiveQuery/build/reports/

Get Code Coverage Reports

./gradlew clean jacocoTestReport

Results can be found in ParseLiveQuery/build/reports/

How Do I Contribute?

We want to make contributing to this project as easy and transparent as possible. Please refer to the Contribution Guidelines.