Package io.realm.mongodb.sync

Interface SubscriptionSet

All Superinterfaces:

Iterable<Subscription>

All Known Subinterfaces:

MutableSubscriptionSet

public interface SubscriptionSet
extends Iterable<Subscription>

A subscription set is an immutable view of all current Subscriptions for a given Realm that has been configured for flexible sync.

Flexible Sync is a way of defining which data gets synchronized to and from the device using RealmQuerys. The query and its metadata are represented by a Subscription.

A subscription set thus defines all the data that is available to the device and being synchronized with the server. If the subscription set encounters an error, e.g. by containing an invalid query, the entire subscription set will enter an SubscriptionSet.State.ERROR state, and no synchronization will happen until the error has been fixed.

If a subscription is removed, so is the corresponding data, but it is only removed from the device. It isn't deleted on the server.

It is possible to modify a subscription set while offline, but modification isn't accepted by the server before getState() returns SubscriptionSet.State.COMPLETE.

It is possible to force the subscription set to be synchronized with the server by using waitForSynchronization() and its variants.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	SubscriptionSet.State	The possible states a subscription set can be in.
static interface	SubscriptionSet.StateChangeCallback	Callback used when asynchronously waiting for the server to process the subscription set.
static interface	SubscriptionSet.UpdateAsyncCallback	Callback used when asynchronously updating a subscription set.
static interface	SubscriptionSet.UpdateCallback	Interface used when modifying a subscription set.

Method Summary

Modifier and Type	Method	Description
Subscription	find(RealmQuery query)	Find the first subscription that contains the given query.
Subscription	find(String name)	Find the subscription with a given name.
String	getErrorMessage()	If getState() returns SubscriptionSet.State.ERROR, this method will return the reason.
SubscriptionSet.State	getState()	Returns the current state of the SubscriptionSet.
int	size()	Returns how many subscriptions are currently in this subscription set.
SubscriptionSet	update(SubscriptionSet.UpdateCallback action)	Modify the subscription set.
RealmAsyncTask	updateAsync(SubscriptionSet.UpdateAsyncCallback callback)	Asynchronously modify the subscription set.
boolean	waitForSynchronization()	Wait for the subscription set to synchronize with the server.
boolean	waitForSynchronization(Long timeOut, TimeUnit unit)	Wait for the subscription set to synchronize with the server.
RealmAsyncTask	waitForSynchronizationAsync(SubscriptionSet.StateChangeCallback callback)	Asynchronously wait for the subscription set to synchronize with the server.
RealmAsyncTask	waitForSynchronizationAsync(Long timeOut, TimeUnit unit, SubscriptionSet.StateChangeCallback callback)	Asynchronously wait for the subscription set to synchronize with the server.

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Method Detail

find

@Nullable
Subscription find(RealmQuery query)

Find the first subscription that contains the given query. It is possible for multiple named subscriptions to contain the same query.

Parameters:

query - query to search for.

Returns:

the first subscription containing the query or null if no match was found.

find

@Nullable
Subscription find(String name)

Find the subscription with a given name.

Parameters:

name - name of subscription to search for.

Returns:

the matching subscription or null if no subscription with that name was found.

getState

SubscriptionSet.State getState()

Returns the current state of the SubscriptionSet. See SubscriptionSet.State for more details about each state.

Returns:

current state of the SubscriptionSet.

size

int size()

Returns how many subscriptions are currently in this subscription set.

Returns:

the number of of subscriptions in the subscription set.

getErrorMessage

@Nullable
String getErrorMessage()

If getState() returns SubscriptionSet.State.ERROR, this method will return the reason. Errors can be fixed by modifying the subscription accordingly and then calling waitForSynchronization().

Returns:

the underlying error if the subscription set is in the SubscriptionSet.State.ERROR state. For all other states null will be returned.

waitForSynchronization

boolean waitForSynchronization()

Wait for the subscription set to synchronize with the server. It will return when the server either accepts the set of queries and has downloaded data for them, or if an error has occurred. Note, that you will either need to manually call BaseRealm.refresh() or wait for change listeners to trigger to see the downloaded data. If an error occurred, the underlying reason can be found through getErrorMessage().

Returns:

true if all current subscriptions were accepted by the server and data has been downloaded, or false if an error occurred.

waitForSynchronization

boolean waitForSynchronization(Long timeOut,
                               TimeUnit unit)

Wait for the subscription set to synchronize with the server. It will return when the server either accepts the set of queries and has downloaded data for them, or if an error has occurred. Note, that you will either need to manually call BaseRealm.refresh() or wait for change listeners to trigger to see the downloaded data. If an error occurred, the underlying reason can be found through getErrorMessage().

Parameters:

timeOut - how long to wait for the synchronization to either succeed or fail.

unit - unit of time used for the timeout.

Returns:

true if all current subscriptions were accepted by the server and data has been downloaded, or false if an error occurred.

Throws:

RuntimeException - if the timeout is exceeded.

waitForSynchronizationAsync

RealmAsyncTask waitForSynchronizationAsync(SubscriptionSet.StateChangeCallback callback)

Asynchronously wait for the subscription set to synchronize with the server. It will invoke the callback when the server either accepts the set of queries and has downloaded data for them, or if an error has occurred. Note, that you will either need to manually call BaseRealm.refresh() or wait for change listeners to trigger to see the downloaded data. If an error occurred, the underlying reason can be found through getErrorMessage().

Parameters:

callback - callback to trigger when the synchronization either succeed or fail. Results will be reported on the UI thread.

Returns:

true if all current subscriptions were accepted by the server and data has been downloaded, or false if an error occurred.

waitForSynchronizationAsync

RealmAsyncTask waitForSynchronizationAsync(Long timeOut,
                                           TimeUnit unit,
                                           SubscriptionSet.StateChangeCallback callback)

Asynchronously wait for the subscription set to synchronize with the server. The callback is invoked when the server either accepts the set of queries and has downloaded data for them, or if an error has occurred. Note, that you will either need to manually call BaseRealm.refresh() or wait for change listeners to trigger to see the downloaded data. If an error occurred, the underlying reason can be found through getErrorMessage().

Parameters:

timeOut - how long to wait for the synchronization to either succeed or fail.

unit - unit of time used for the timeout.

callback - callback to trigger when the synchronization either succeed or fail. Results will be reported on the UI thread.

Returns:

true if all current subscriptions were accepted by the server and data has been downloaded, or false if an error occurred.

update

SubscriptionSet update(SubscriptionSet.UpdateCallback action)

Modify the subscription set. If an exception is thrown during the update, no changes will be applied. If the update succeeds, this subscription set is updated with the modified state.

Parameters:

action - the block that modifies the subscription set. It will run on the caller thread.

Returns:

this subscription set, that now has been updated.

Throws:

Exception - any exception thrown during the update, will propagate back.

updateAsync

RealmAsyncTask updateAsync(SubscriptionSet.UpdateAsyncCallback callback)

Asynchronously modify the subscription set. If an exception is thrown during the update, no changes will be applied. *

Parameters:

callback - callback that controls the asynct ask. Succces or failure will be reported here.

Returns:

task controlling the async execution.