Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Device SDKs
/
Java SDK
/
API Reference
/
io.realm.mongodb.sync

Interface SubscriptionSet

On this page

  • io.realm.mongodb.sync
  • Nested Class Summary
  • Method Summary
  • Inherited Methods
  • Method Detail
  • find
  • getErrorMessage
  • getState
  • size
  • update
  • updateAsync
  • waitForSynchronization
  • waitForSynchronizationAsync

io.realm.mongodb.sync

Implemented interfaces:

  • java.lang.Iterable

A subscription set is an immutable view of all current Subscription s 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 RealmQuery s. 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

Modifier and Type
Class and Description
public static final
public static interface
public static interface
public static interface

Method Summary

Modifier and Type
Method and Description
find (
String name
)

Find the subscription with a given name.

find (
io.realm.RealmQuery query
)

Find the first subscription that contains the given query.

public String
getErrorMessage ()

If getState() returns State.ERROR , this method will return the reason.

getState ()

Returns the current state of the SubscriptionSet.

public int
size ()

Returns how many subscriptions are currently in this subscription set.

update (
SubscriptionSet.UpdateCallback action
)

Modify the subscription set.

updateAsync (
SubscriptionSet.UpdateAsyncCallback callback
)

Asynchronously modify the subscription set.

public boolean
waitForSynchronization (
Long timeOut,
TimeUnit unit
)

Wait for the subscription set to synchronize with the server.

public boolean
waitForSynchronization ()

Wait for the subscription set to synchronize with the server.

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

Asynchronously wait for the subscription set to synchronize with the server.

waitForSynchronizationAsync (
SubscriptionSet.StateChangeCallback callback
)

Asynchronously wait for the subscription set to synchronize with the server.

Inherited Methods

Method Detail

find

public 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.

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.

getErrorMessage

If getState() returns 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 State.ERROR state. For all other states null will be returned.

getState

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

Returns

current state of the SubscriptionSet.

size

public int size ()

Returns how many subscriptions are currently in this subscription set.

Returns

the number of of subscriptions in the subscription set.

update

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

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.

waitForSynchronization

public 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 Realm.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

public 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 Realm.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.

waitForSynchronizationAsync

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 Realm.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.

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 Realm.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.

Back

Subscription

Next

SubscriptionSet.State