io.realm.sync

Class Subscription

java.lang.Object

io.realm.RealmObject

io.realm.sync.Subscription

All Implemented Interfaces:

RealmModel

public class Subscription
extends RealmObject

Subscriptions represents the data from the server that a device is interested in when using Query-based Realms.

They are created automatically when using RealmQuery.findAllAsync() or RealmQuery.findAllAsync(String) on those Realms, but can also be created manually using RealmQuery.subscribe() and RealmQuery.subscribe(String).

As long as any subscription exist that include an object, that object will be present on the device. If an object is not covered by an active subscription it will be removed from the device, but not the server.

Subscriptions are Realm objects, so deleting them e.g. by calling RealmObject.deleteFromRealm(), is the same as calling unsubscribe().

Warning: Instances of this class should never be created directly through Realm.createObject(Class) but only by using RealmQuery.subscribe() or RealmQuery.subscribe(String).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Subscription.State The different states a Subscription can be in.

Constructor Summary

Constructors

Constructor and Description
Subscription()
Subscription(String name, RealmQuery<?> query) Creates a unmanaged named subscription from a RealmQuery.

Method Summary

Modifier and Type	Method and Description
Date	getCreatedAt() Returns when this subscription was initially created.
String	getErrorMessage() Returns the error message if getState() returned Subscription.State.ERROR, otherwise the empty string is returned.
Date	getExpiresAt() Returns the point in time from which Realm can safely delete this subscription.
String	getName() Returns the name of the subscription.
String	getQueryClassName() Returns the internal name of the Class being queried.
String	getQueryDescription() Returns a textual description of the query that created this subscription.
Subscription.State	getState() Returns the state of the subscription
long	getTimeToLive() Returns for how long the subscription must be kept alive after last being used.
Date	getUpdatedAt() Returns when this subscription was last used or updated.
void	setQuery(RealmQuery query) Replaces the current query controlled by this subscription with a new query.
void	setTimeToLive(long timeToLive, TimeUnit timeUnit) Sets the time-to-live in milliseconds for this subscription.
String	toString()
void	unsubscribe() Cancels the subscription.

Methods inherited from class io.realm.RealmObject

addChangeListener, addChangeListener, addChangeListener, addChangeListener, asChangesetObservable, asChangesetObservable, asFlowable, asFlowable, deleteFromRealm, deleteFromRealm, freeze, freeze, getRealm, getRealm, isFrozen, isFrozen, isLoaded, isLoaded, isManaged, isManaged, isValid, isValid, load, load, removeAllChangeListeners, removeAllChangeListeners, removeChangeListener, removeChangeListener, removeChangeListener, removeChangeListener

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Subscription

public Subscription()

Subscription

public Subscription(String name,
                    RealmQuery<?> query)

Creates a unmanaged named subscription from a RealmQuery. This will not take effect until it has been added to the Realm.

Parameters:

name - name of the query.

query - the query to turn into a subscription.

Method Detail

getName

public String getName()

Returns the name of the subscription.

Returns:

the name of the subscription.

getCreatedAt

public Date getCreatedAt()

Returns when this subscription was initially created. If new Date(0) is returned, it is unknown when the subscription was created.

Returns:

when this subscription was initially created.

getUpdatedAt

public Date getUpdatedAt()

Returns when this subscription was last used or updated.

"Used" in this context means that someone resubscribed to the subscription.

"Updated" means that someone updated the query or some other field part of this class.

This field is NOT updated whenever the results of the query changes.

This field plus timeToLive defines expiresAt.

Returns:

the point in time this subscription was last used or updated.

getExpiresAt

public Date getExpiresAt()

Returns the point in time from which Realm can safely delete this subscription. This will happen automatically.

Realm will attempt to cleanup expired subscriptions when the app is started or whenever any subscription is modified, there is no guarantee it will happen immediately after it expires.

Returns:

the point in time after which Realm can safely delete this subscription.

getTimeToLive

public long getTimeToLive()

Returns for how long the subscription must be kept alive after last being used. The value returned are in milliseconds.

Returns:

in milliseconds, for how long the subscription must be kept alive after last being used.

setTimeToLive

public void setTimeToLive(long timeToLive,
                          TimeUnit timeUnit)

Sets the time-to-live in milliseconds for this subscription. This defines for how long Realm must keep the subscription alive after last being used.

Parameters:

timeToLive - for how long Realm must keep the subscription after last being used.

timeUnit - time unit for timeToLive.

Throws:

IllegalArgumentException - if a negative time-to-live or null timeUnit is provided.

getQueryDescription

public String getQueryDescription()

Returns a textual description of the query that created this subscription.

Returns:

a textual description of the query.

setQuery

public void setQuery(RealmQuery query)

Replaces the current query controlled by this subscription with a new query.

Parameters:

query - the query which should replace the current one.

getQueryClassName

public String getQueryClassName()

Returns the internal name of the Class being queried.

Returns:

the internal name of the of the class being queried.

getState

public Subscription.State getState()

Returns the state of the subscription

Returns:

the state of the subscription.

See Also:

Subscription.State

getErrorMessage

public String getErrorMessage()

Returns the error message if getState() returned Subscription.State.ERROR, otherwise the empty string is returned.

Returns:

the error string if the subscription encountered an error.

unsubscribe

public void unsubscribe()

Cancels the subscription. After this, if the objects covered by the subscription are not part of any other subscription, they will be removed locally from the device (but not on the server).

The effect of unsubscribing is not immediate. The local Realm must coordinate with the Realm Object Server before it can happen. When it happens, any objects removed will trigger a standard change notification, and from the perspective of the device it will look like they where deleted.

Calling this method is the equivalent of calling RealmObject.deleteFromRealm().

Throws:

IllegalStateException - if the Realm is not in a write transaction.

toString

public String toString()

Overrides:

toString in class Object