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.

    • 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.
      • size

        int size()
        Returns how many subscriptions are currently in this subscription set.
        Returns:
        the number of of subscriptions in the subscription set.
      • 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.